Class: Synthra::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/synthra/configuration.rb

Overview

Global configuration settings for Synthra

The Configuration class holds all global settings that affect how Synthra behaves. Settings include default generation mode, uniqueness retry limits, and resource limits.

Access the configuration via configuration or modify it using configure.

Examples:

Access configuration

config = Synthra.configuration
config.default_mode        # => :random
config.max_unique_retries  # => 1000

Modify configuration

Synthra.configure do |config|
  config.default_mode = :mixed
  config.null_optional = true
end

Reset to defaults

Synthra.reset_configuration!

Constant Summary collapse

VALID_MODES =

Valid generation modes

Modes:

  • :random - Standard fake data generation using Faker
  • :edge - Generate edge case values (empty strings, nulls, extremes)
  • :invalid - Generate intentionally invalid data for validation testing
  • :hostile - Generate security attack payloads (SQL injection, XSS, buffer overflow)
  • :mixed - Probabilistically mix all modes (80% random, 15% edge, 5% invalid)

Returns:

  • (Array<Symbol>) —

    the list of valid mode symbols

%i[random edge invalid hostile mixed].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Create a new Configuration with default values

Examples:

config = Synthra::Configuration.new
config.default_mode  # => :random


175
176
177
 
# File 'lib/synthra/configuration.rb', line 175

def initialize
  reset!
end

Instance Attribute Details

#allow_eval ⇒ Boolean

Note:

Enabling eval is a security risk and should only be used in trusted environments

Whether to allow eval() in custom expressions (default: false)

Returns:

  • (Boolean) —

    true to allow eval, false to disallow



71
72
73
 
# File 'lib/synthra/configuration.rb', line 71

def allow_eval
  @allow_eval
end

#default_mode ⇒ Object

Returns the value of attribute default_mode.



163
164
165
 
# File 'lib/synthra/configuration.rb', line 163

def default_mode
  @default_mode
end

#fast_mode ⇒ Boolean

Note:

FastEngine is optimized for batch generation but is NOT thread-safe

Whether to use FastEngine for batch generation (default: false)

Returns:

  • (Boolean) —

    true to use FastEngine, false to use standard Engine



140
141
142
 
# File 'lib/synthra/configuration.rb', line 140

def fast_mode
  @fast_mode
end

#logger ⇒ Logger?

Optional logger for observability (Logger instance or compatible object)

Returns:

  • (Logger, nil) —

    logger instance or nil



100
101
102
 
# File 'lib/synthra/configuration.rb', line 100

def logger
  @logger
end

#max_unique_retries ⇒ Integer

Maximum attempts to generate a unique value before giving up

Returns:

  • (Integer) —

    the maximum retry count (default: 1000)

See Also:



79
80
81
 
# File 'lib/synthra/configuration.rb', line 79

def max_unique_retries
  @max_unique_retries
end

#metrics_collector ⇒ Object?

Optional metrics collector for observability

Returns:

  • (Object, nil) —

    metrics collector instance or nil



147
148
149
 
# File 'lib/synthra/configuration.rb', line 147

def metrics_collector
  @metrics_collector
end

#null_optional ⇒ Boolean

Whether optional fields should default to null/nil

Returns:

  • (Boolean) —

    true to default optional to null (default: false)



86
87
88
 
# File 'lib/synthra/configuration.rb', line 86

def null_optional
  @null_optional
end

#nullable_field_null_rate ⇒ Float

Probability that a nullable field will be null (default: 0.1 = 10%)

Returns:

  • (Float) —

    probability between 0.0 and 1.0



132
133
134
 
# File 'lib/synthra/configuration.rb', line 132

def nullable_field_null_rate
  @nullable_field_null_rate
end

#on_field_generated ⇒ Proc?

Note:

Callback receives (field_name, value, context) as arguments

Optional callback invoked when a field is generated

Returns:

  • (Proc, nil) —

    callback proc or nil



155
156
157
 
# File 'lib/synthra/configuration.rb', line 155

def on_field_generated
  @on_field_generated
end

#optional_field_presence_rate ⇒ Float

Probability that an optional field will be included in output (default: 0.8 = 80%)

Returns:

  • (Float) —

    probability between 0.0 and 1.0



125
126
127
 
# File 'lib/synthra/configuration.rb', line 125

def optional_field_presence_rate
  @optional_field_presence_rate
end

#registry_cache_size ⇒ Integer

Maximum number of AST entries to cache in the registry

Returns:

  • (Integer) —

    the maximum cache size (default: 100)



93
94
95
 
# File 'lib/synthra/configuration.rb', line 93

def registry_cache_size
  @registry_cache_size
end

#validate_paths_on_load ⇒ Boolean

Note:

This catches typos in copy() paths at load time rather than at generation time, preventing silent nil values

Whether to automatically validate copy() paths when loading schemas

Returns:

  • (Boolean) —

    true to validate on load (default: true)



118
119
120
 
# File 'lib/synthra/configuration.rb', line 118

def validate_paths_on_load
  @validate_paths_on_load
end

#warn_on_shared_misuse ⇒ Boolean

Note:

When shared() is used with generate() instead of generate_many(), values won't be shared across calls, which may be unintended behavior

Whether to emit warnings when shared() is used outside generate_many()

Returns:

  • (Boolean) —

    true to emit warnings (default: true)



109
110
111
 
# File 'lib/synthra/configuration.rb', line 109

def warn_on_shared_misuse
  @warn_on_shared_misuse
end

Instance Method Details

#limits ⇒ Limits

Access the resource limits configuration

The limits object controls maximum values for latency, recursion depth, and array sizes to prevent runaway generation.

Examples:

Configure limits

Synthra.configure do |config|
  config.limits.max_latency_ms = 10000   # 10 seconds
  config.limits.max_recursion = 5        # 5 levels deep
  config.limits.max_array_size = 100     # 100 elements max
end

Returns:

  • (Limits) —

    the limits configuration object



195
196
197
 
# File 'lib/synthra/configuration.rb', line 195

def limits
  @limits ||= Limits.new
end

#observability_enabled? ⇒ Boolean

Check if observability features are enabled

Returns true if any of the observability features (metrics, logging, or field generation callbacks) are configured. Used to optimize the hot path by avoiding unnecessary checks.

Examples:

config.observability_enabled?  # => false (by default)
config.logger = Logger.new(STDOUT)
config.observability_enabled?  # => true

Returns:

  • (Boolean) —

    true if observability is enabled



277
278
279
 
# File 'lib/synthra/configuration.rb', line 277

def observability_enabled?
  !!(@metrics_collector || @logger || @on_field_generated)
end

#reset! ⇒ void

This method returns an undefined value.

Reset all configuration settings to their defaults

This method restores all settings to their initial values:

  • allow_eval: false
  • default_mode: :random
  • max_unique_retries: 1000
  • null_optional: false
  • limits: new Limits instance with defaults

Examples:

Reset after tests

after(:each) do
  Synthra.configuration.reset!
end


245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/synthra/configuration.rb', line 245

def reset!
  @allow_eval = false
  @default_mode = :random
  @max_unique_retries = 1000
  @null_optional = false
  @limits = nil  # Will be lazily initialized with defaults
  @logger = nil
  @metrics_collector = nil
  @on_field_generated = nil
  @registry_cache_size = 100
  @warn_on_shared_misuse = true  # Warn when shared() used outside generate_many()
  @validate_paths_on_load = true  # Auto-validate copy() paths on schema load
  @optional_field_presence_rate = Synthra::OPTIONAL_FIELD_PRESENCE_RATE
  @nullable_field_null_rate = Synthra::NULLABLE_FIELD_NULL_RATE
  @fast_mode = false  # Use standard Engine by default (thread-safe)
end