foxhunt/proto/config.proto

syntax = "proto3";

package config;

// Configuration Service provides centralized, PostgreSQL-based configuration management with hot-reload capabilities.
// This service supports real-time configuration updates, validation, history tracking, and import/export functionality
// for all trading system components with comprehensive audit trails and rollback capabilities.
service ConfigService {
  // Configuration CRUD Operations
  // Get configuration settings by category, key, or environment
  rpc GetConfiguration(GetConfigurationRequest) returns (GetConfigurationResponse);
  
  // Update configuration value with validation and audit logging
  rpc UpdateConfiguration(UpdateConfigurationRequest) returns (UpdateConfigurationResponse);
  
  // Delete configuration setting with audit trail
  rpc DeleteConfiguration(DeleteConfigurationRequest) returns (DeleteConfigurationResponse);
  
  // List available configuration categories
  rpc ListCategories(ListCategoriesRequest) returns (ListCategoriesResponse);

  // Real-time Configuration Streaming
  // Stream real-time configuration changes with hot-reload support
  rpc StreamConfigChanges(StreamConfigChangesRequest) returns (stream ConfigChangeEvent);

  // Configuration Management Operations
  // Validate configuration value against schema and rules
  rpc ValidateConfiguration(ValidateConfigurationRequest) returns (ValidateConfigurationResponse);
  
  // Get configuration change history with audit details
  rpc GetConfigurationHistory(GetConfigurationHistoryRequest) returns (GetConfigurationHistoryResponse);
  
  // Rollback configuration to previous value
  rpc RollbackConfiguration(RollbackConfigurationRequest) returns (RollbackConfigurationResponse);
  
  // Export configuration data in various formats
  rpc ExportConfiguration(ExportConfigurationRequest) returns (ExportConfigurationResponse);
  
  // Import configuration data with validation
  rpc ImportConfiguration(ImportConfigurationRequest) returns (ImportConfigurationResponse);

  // Schema Management Operations
  // Get configuration schema definitions
  rpc GetConfigSchema(GetConfigSchemaRequest) returns (GetConfigSchemaResponse);
  
  // Update configuration schema with validation rules
  rpc UpdateConfigSchema(UpdateConfigSchemaRequest) returns (UpdateConfigSchemaResponse);
}

// Configuration CRUD Messages
message GetConfigurationRequest {
  optional string category = 1;
  optional string key = 2;
  optional string environment = 3;
}

message GetConfigurationResponse {
  repeated ConfigurationSetting settings = 1;
}

message UpdateConfigurationRequest {
  string category = 1;
  string key = 2;
  string value = 3;
  string changed_by = 4;
  optional string change_reason = 5;
  optional string environment = 6;
}

message UpdateConfigurationResponse {
  bool success = 1;
  string message = 2;
  optional ValidationResult validation_result = 3;
  int64 timestamp = 4;
}

message DeleteConfigurationRequest {
  string category = 1;
  string key = 2;
  string deleted_by = 3;
  optional string delete_reason = 4;
}

message DeleteConfigurationResponse {
  bool success = 1;
  string message = 2;
  int64 timestamp = 3;
}

message ListCategoriesRequest {
  optional string parent_category = 1;
}

message ListCategoriesResponse {
  repeated ConfigurationCategory categories = 1;
}

// Streaming Messages
message StreamConfigChangesRequest {
  repeated string categories = 1;
  repeated string keys = 2;
}

// Validation Messages
message ValidateConfigurationRequest {
  string category = 1;
  string key = 2;
  string value = 3;
}

message ValidateConfigurationResponse {
  bool is_valid = 1;
  ValidationResult validation_result = 2;
}

// History Messages
message GetConfigurationHistoryRequest {
  optional string category = 1;
  optional string key = 2;
  optional int64 start_time = 3;
  optional int64 end_time = 4;
  optional int32 limit = 5;
}

message GetConfigurationHistoryResponse {
  repeated ConfigurationHistoryEntry history = 1;
}

message RollbackConfigurationRequest {
  string category = 1;
  string key = 2;
  int64 rollback_to_timestamp = 3;
  string rolled_back_by = 4;
  optional string rollback_reason = 5;
}

message RollbackConfigurationResponse {
  bool success = 1;
  string message = 2;
  ConfigurationSetting restored_setting = 3;
  int64 timestamp = 4;
}

// Import/Export Messages
message ExportConfigurationRequest {
  repeated string categories = 1;
  optional string environment = 2;
  ExportFormat format = 3;
}

message ExportConfigurationResponse {
  string exported_data = 1;
  ExportFormat format = 2;
  int32 settings_count = 3;
  int64 exported_at = 4;
}

message ImportConfigurationRequest {
  string imported_data = 1;
  ExportFormat format = 2;
  string imported_by = 3;
  bool dry_run = 4;
  bool overwrite_existing = 5;
}

message ImportConfigurationResponse {
  bool success = 1;
  string message = 2;
  repeated ImportResult import_results = 3;
  int32 imported_count = 4;
  int32 skipped_count = 5;
  int32 error_count = 6;
}

// Schema Messages
message GetConfigSchemaRequest {
  optional string category = 1;
}

message GetConfigSchemaResponse {
  repeated ConfigurationSchema schemas = 1;
}

message UpdateConfigSchemaRequest {
  string schema_name = 1;
  string schema_definition = 2;
  string updated_by = 3;
}

message UpdateConfigSchemaResponse {
  bool success = 1;
  string message = 2;
  int64 timestamp = 3;
}

// Core Data Types

// Complete configuration setting with metadata and validation rules
message ConfigurationSetting {
  int64 id = 1;                         // Unique setting identifier
  string category = 2;                  // Configuration category (e.g., "trading.limits")
  string key = 3;                       // Configuration key (e.g., "max_position_size")
  string value = 4;                     // Current configuration value
  ConfigDataType data_type = 5;         // Data type (string, number, boolean, etc.)
  bool hot_reload = 6;                  // Whether changes trigger hot-reload
  string description = 7;               // Human-readable description
  optional string default_value = 8;    // Default value if not set
  bool required = 9;                    // Whether this setting is required
  bool sensitive = 10;                  // Whether value contains sensitive data
  optional string validation_rule = 11; // Validation rule expression
  optional string environment_override = 12; // Environment-specific override
  optional double min_value = 13;       // Minimum numeric value
  optional double max_value = 14;       // Maximum numeric value
  optional string enum_values = 15;     // Allowed enum values (comma-separated)
  repeated string depends_on = 16;      // Dependencies on other settings
  repeated string tags = 17;            // Tags for categorization
  int32 display_order = 18;             // Display order in UI
  int64 created_at = 19;                // Creation timestamp
  int64 modified_at = 20;               // Last modification timestamp
}

message ConfigurationCategory {
  int64 id = 1;
  string name = 2;
  string description = 3;
  optional int64 parent_id = 4;
  int32 display_order = 5;
  optional string icon = 6;
  int64 created_at = 7;
  repeated ConfigurationCategory children = 8;
}

message ConfigurationHistoryEntry {
  int64 id = 1;
  int64 setting_id = 2;
  optional string old_value = 3;
  string new_value = 4;
  optional string change_reason = 5;
  string changed_by = 6;
  int64 changed_at = 7;
  string change_source = 8;
  optional ValidationResult validation_result = 9;
  optional int64 rollback_id = 10;
}

message ConfigurationSchema {
  int64 id = 1;
  string name = 2;
  string schema_definition = 3;
  string description = 4;
  int64 created_at = 5;
}

message ValidationResult {
  bool is_valid = 1;
  repeated ValidationError errors = 2;
  repeated ValidationWarning warnings = 3;
}

message ValidationError {
  string field = 1;
  string message = 2;
  string error_code = 3;
}

message ValidationWarning {
  string field = 1;
  string message = 2;
  string warning_code = 3;
}

message ImportResult {
  string category = 1;
  string key = 2;
  ImportStatus status = 3;
  optional string error_message = 4;
}

// Event Messages
message ConfigChangeEvent {
  int64 setting_id = 1;
  string category = 2;
  string key = 3;
  string old_value = 4;
  string new_value = 5;
  string changed_by = 6;
  int64 timestamp = 7;
  ConfigChangeType change_type = 8;
  bool hot_reload = 9;
}

// Enums

// Data types for configuration values
enum ConfigDataType {
  CONFIG_DATA_TYPE_UNSPECIFIED = 0;     // Default/unknown type
  CONFIG_DATA_TYPE_STRING = 1;          // Text string value
  CONFIG_DATA_TYPE_NUMBER = 2;          // Numeric value (int or float)
  CONFIG_DATA_TYPE_BOOLEAN = 3;         // Boolean true/false value
  CONFIG_DATA_TYPE_JSON = 4;            // JSON object or array
  CONFIG_DATA_TYPE_ENCRYPTED = 5;       // Encrypted sensitive value
}

enum ExportFormat {
  EXPORT_FORMAT_UNSPECIFIED = 0;
  EXPORT_FORMAT_JSON = 1;
  EXPORT_FORMAT_YAML = 2;
  EXPORT_FORMAT_TOML = 3;
  EXPORT_FORMAT_ENV = 4;
}

enum ImportStatus {
  IMPORT_STATUS_UNSPECIFIED = 0;
  IMPORT_STATUS_SUCCESS = 1;
  IMPORT_STATUS_SKIPPED = 2;
  IMPORT_STATUS_ERROR = 3;
  IMPORT_STATUS_VALIDATION_FAILED = 4;
}

enum ConfigChangeType {
  CONFIG_CHANGE_TYPE_UNSPECIFIED = 0;
  CONFIG_CHANGE_TYPE_CREATED = 1;
  CONFIG_CHANGE_TYPE_UPDATED = 2;
  CONFIG_CHANGE_TYPE_DELETED = 3;
  CONFIG_CHANGE_TYPE_ROLLBACK = 4;
}