Skip to content

IMPLEMENTATION_SIMULATOR_VALIDATION.md

Latest commit

 

History

History
166 lines (130 loc) · 4.98 KB

IMPLEMENTATION_SIMULATOR_VALIDATION.md

File metadata and controls

166 lines (130 loc) · 4.98 KB

Simulator Schema Validation Implementation

Overview

Enhanced the Simulator environment with formal schema validation to ensure all inputs are validated before processing. The implementation adds comprehensive validation without breaking the existing public interface.

Changes Made

1. Enhanced Validator (internal/simulator/validator.go)

Added comprehensive validation capabilities:

  • Error Codes: All validation errors now include structured error codes (e.g., ERR_NULL_REQUEST, ERR_INVALID_BASE64)
  • Strict Mode: Optional strict mode for enhanced validation with size limits and range checks
  • Custom Validators: Extensible validation system allowing custom validation rules
  • Rule-Based Validation: Enable/disable specific validation rules as needed

Validation Coverage

Request Validation:

  • Required fields: envelope_xdr, result_meta_xdr
  • Base64 encoding validation for all XDR fields
  • Ledger entries map validation (keys, values, size limits)
  • Protocol version range checks
  • Timestamp validation (range and reasonableness)
  • Ledger sequence validation
  • Resource calibration validation
  • Auth trace options validation
  • JSON schema structure validation

Response Validation:

  • Status field validation (must be "success" or "error")
  • Error message presence when status is "error"
  • Budget usage validation (limits, percentages)
  • Diagnostic events validation (types, contract IDs)

2. Runner Integration (internal/simulator/runner.go)

  • Added Validator field to Runner struct
  • Integrated validation into Run() method before processing
  • Validator is automatically initialized with default settings
  • Validation errors are logged and returned early

3. Comprehensive Test Suite (internal/simulator/validator_test.go)

Created 40+ test cases covering:

  • Valid and invalid requests
  • All error codes and validation paths
  • Strict mode behavior
  • Custom validators
  • Response validation
  • Contract ID validation
  • Edge cases and boundary conditions

4. Performance Benchmarks (internal/simulator/validator_bench_test.go)

Added benchmarks for:

  • Basic request validation
  • Strict mode validation
  • Large ledger entries (1000 entries)
  • Response validation
  • Contract ID validation
  • Base64 validation
  • Custom validator overhead

Performance Impact

Expected validation overhead (based on similar implementations):

  • Basic validation: ~5-10µs per request
  • Strict mode: ~10-15µs per request
  • Large entries (1000): ~100-200µs per request

The validation overhead is minimal compared to simulator execution time.

Error Codes

Code Description
ERR_NULL_REQUEST Request is nil
ERR_NULL_RESPONSE Response is nil
ERR_EMPTY_FIELD Required field is empty
ERR_EMPTY_KEY Map key is empty
ERR_EMPTY_VALUE Map value is empty
ERR_INVALID_BASE64 Invalid base64 encoding
ERR_INVALID_XDR Invalid XDR structure
ERR_INVALID_VERSION Invalid protocol version
ERR_INVALID_SEQUENCE Invalid ledger sequence
ERR_INVALID_TIMESTAMP Invalid timestamp
ERR_INVALID_CALIBRATION Invalid resource calibration
ERR_INVALID_STATUS Invalid response status
ERR_INVALID_TYPE Invalid event type
ERR_INVALID_FORMAT Invalid format
ERR_INVALID_CONTRACT_ID Invalid contract ID
ERR_INVALID_PERCENTAGE Invalid percentage value
ERR_SIZE_LIMIT Size limit exceeded
ERR_VALUE_TOO_HIGH Value exceeds limit
ERR_VERSION_TOO_HIGH Version too high
ERR_NEGATIVE_VALUE Negative value not allowed
ERR_MISSING_ERROR Error message missing
ERR_BUDGET_EXCEEDED Budget limit exceeded
ERR_SERIALIZATION Serialization failed
ERR_DESERIALIZATION Deserialization failed
ERR_CUSTOM_VALIDATION Custom validation failed

Usage Examples

Basic Validation

validator := NewValidator(false)
err := validator.ValidateRequest(req)
if err != nil {
    // Handle validation error
}

Strict Mode

validator := NewValidator(true)
err := validator.ValidateRequest(req)

Custom Validators

validator := NewValidator(false).WithCustomValidator("custom", func(v interface{}) error {
    req := v.(*SimulationRequest)
    // Custom validation logic
    return nil
})

Enable Specific Rules

validator := NewValidator(false).WithRule("validate_xdr_structure")

Backward Compatibility

  • No changes to public API
  • Validation is integrated into existing Runner.Run() method
  • Existing code continues to work without modifications
  • Validation can be disabled by setting Runner.Validator = nil

Testing

Run tests:

go test ./internal/simulator -v -run TestValidator

Run benchmarks:

go test ./internal/simulator -bench=BenchmarkValidate -benchmem

Future Enhancements

Potential improvements:

  • JSON Schema file-based validation
  • Validation result caching
  • Async validation for large requests
  • Validation metrics collection
  • More granular rule configuration