synthra 0.1.0

data/lib/synthra/behaviors/applicator.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Behaviors Applicator
+# =============================================================================
+#
+# The Applicator is responsible for applying behaviors to generated data.
+# It handles both schema-level behaviors (applied to entire records) and
+# field-level behaviors (applied to individual field values).
+#
+# @example Usage (internal)
+#   applicator = Applicator.new(schema, rng)
+#   result = applicator.apply_schema_behaviors(generated_record)
+#
+# =============================================================================
+
+
+module Synthra
+  module Behaviors
+
+    # Applies behaviors to generated data
+    #
+    # The Applicator coordinates behavior application, looking up behavior
+    # classes from the registry and applying them in order. It handles
+    # both schema-level and field-level behaviors.
+    #
+    # @example Apply schema behaviors
+    #   applicator = Applicator.new(schema, rng)
+    #   result = applicator.apply_schema_behaviors({ "name" => "John" })
+    #   # May add latency, raise errors, etc.
+    #
+    # @example Apply field behaviors
+    #   value = applicator.apply_field_behaviors(field, "original_value")
+    #   # => modified value or :omit to remove field
+    #
+
+    class Applicator
+
+      # Create a new Applicator
+      #
+      # @param schema [Schema] the schema containing behavior definitions
+      # @param rng [Generator::RNG] random number generator for deterministic behavior
+      #
+      # @example
+      #   applicator = Applicator.new(schema, rng)
+      #
+
+      def initialize(schema, rng)
+        @schema = schema
+        @rng = rng
+      end
+
+
+      # Apply schema-level behaviors to a generated record
+      #
+      # Applies all behaviors defined at the schema level (e.g., @latency,
+      # @failure) to the complete generated record. Behaviors are applied
+      # in the order they were defined.
+      #
+      # @param result [Hash] the generated record
+      # @return [Hash] the result after all behaviors have been applied
+      # @raise [SimulatedFailure] if failure behavior triggers
+      # @raise [SimulatedConnectionDrop] if close_connection behavior triggers
+      # @raise [SimulatedError] if simulate_error behavior triggers
+      #
+      # @example
+      #   # Schema with @latency 100ms @failure 10%
+      #   result = applicator.apply_schema_behaviors({ "id" => "123" })
+      #   # May add 100ms delay, or raise SimulatedFailure 10% of the time
+      #
+
+      def apply_schema_behaviors(result)
+        @schema.all_behaviors.each do |behavior_config|
+          name = behavior_config[:name]
+          value = behavior_config[:value]
+
+          begin
+
+            # Look up the behavior class from registry
+            behavior_class = Registry.lookup(name)
+
+
+            # Create behavior instance
+            # Handle both Class and BlockBehavior patterns
+            behavior = behavior_class.respond_to?(:new) ?
+              (behavior_class.is_a?(Class) ? behavior_class.new(value, @rng) : behavior_class.new(value, @rng)) :
+              behavior_class
+
+
+            # Apply the behavior, which may modify result or raise errors
+            result = behavior.apply(result)
+          rescue ArgumentError => e
+
+            # Only skip if it's an "Unknown behavior" error
+            # Re-raise other ArgumentErrors (e.g., wrong number of arguments)
+            if e.message.include?("Unknown behavior")
+
+              # Unknown behavior - skip silently
+              # This allows forward compatibility with unknown behaviors
+            else
+
+              # Re-raise real argument errors
+              raise
+            end
+          end
+        end
+        result
+      end
+
+
+      # Apply field-level behaviors to a field value
+      #
+      # Applies behaviors defined on individual fields (e.g., @partial_data,
+      # @latency). Field behaviors can modify the value or indicate that
+      # the field should be omitted entirely.
+      #
+      # @param field [Field] the field definition with behaviors
+      # @param value [Object] the generated field value
+      # @return [Object, Symbol] the modified value, or :omit to remove the field
+      #
+      # @example Apply partial_data behavior
+      #   # Field with @partial_data 20%
+      #   result = applicator.apply_field_behaviors(field, "value")
+      #   # => "value" (80% of the time) or :omit (20% of the time)
+      #
+
+      def apply_field_behaviors(field, value)
+        field.behaviors.each do |fb|
+          begin
+
+            # Look up and instantiate the behavior
+            behavior_class = Registry.lookup(fb.type)
+            behavior = behavior_class.respond_to?(:new) ?
+              (behavior_class.is_a?(Class) ? behavior_class.new(fb.value, @rng) : behavior_class.new(fb.value, @rng)) :
+              behavior_class
+
+
+            # Special handling for partial_data - return :omit symbol
+            if fb.type == :partial_data && behavior.should_apply?
+              return :omit
+            end
+
+
+            # Apply other behaviors normally
+            value = behavior.apply(value)
+          rescue ArgumentError => e
+
+            # Only skip if it's an "Unknown behavior" error
+            # Re-raise other ArgumentErrors (e.g., wrong number of arguments)
+            if e.message.include?("Unknown behavior")
+
+              # Unknown behavior - skip silently
+            else
+
+              # Re-raise real argument errors
+              raise
+            end
+          end
+        end
+        value
+      end
+    end
+  end
+end

data/lib/synthra/behaviors/base.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Behaviors Base Class
+# =============================================================================
+#
+# The Base class is the foundation for all behavior implementations.
+# Behaviors modify how data is generated or returned, enabling simulation
+# of real-world conditions like network latency, failures, and partial data.
+#
+# Built-in behaviors:
+# - latency: Adds delays to simulate slow responses
+# - failure: Raises errors to simulate service failures
+# - partial_data: Omits fields to simulate incomplete data
+# - close_connection: Simulates connection drops
+# - simulate_error: Simulates specific HTTP errors
+# - randomize_order: Shuffles array elements
+#
+# @example Creating a custom behavior
+#   class MyBehavior < Synthra::Behaviors::Base
+#     def apply(result, context = nil)
+#       return result unless should_apply?
+#       # Modify result here
+#       result.merge("modified" => true)
+#     end
+#   end
+#
+# =============================================================================
+
+
+module Synthra
+  module Behaviors
+
+    # Base class for all behavior implementations
+    #
+    # All behaviors inherit from Base and implement the #apply method.
+    # The base class provides probability-based activation through
+    # #should_apply? method.
+    #
+    # @abstract Subclass and implement {#apply}
+    #
+    # @example Implement a simple behavior
+    #   class Logging < Base
+    #     def apply(result, context = nil)
+    #       return result unless should_apply?
+    #       puts "Generated: #{result.inspect}"
+    #       result
+    #     end
+    #   end
+    #
+
+    class Base
+
+      # @!attribute [r] value
+      #   The behavior configuration value
+      #   @return [Object] configuration (probability, range, etc.)
+
+      attr_reader :value
+
+
+      # @!attribute [r] rng
+      #   Random number generator for deterministic probability checks
+      #   @return [Generator::RNG, nil] RNG instance
+
+      attr_reader :rng
+
+
+      # Create a new behavior instance
+      #
+      # @param value [Object] behavior configuration (probability, range, etc.)
+      # @param rng [Generator::RNG, nil] random number generator for determinism
+      #
+      # @example Create with probability
+      #   Latency.new(100..500, rng)
+      #   Failure.new(10, rng)  # 10% probability
+      #
+
+      def initialize(value, rng = nil)
+        @value = value
+        @rng = rng
+      end
+
+
+      # Apply the behavior to generated data
+      #
+      # This is the main method that behaviors implement to modify
+      # generated data or produce side effects.
+      #
+      # @abstract Must be implemented by subclasses
+      #
+      # @param result [Object] the generated data to modify
+      # @param context [Generator::Context, nil] generation context
+      # @return [Object] the modified result
+      # @raise [NotImplementedError] if not overridden
+      #
+      # @example Implementation
+      #   def apply(result, context = nil)
+      #     return result unless should_apply?
+      #     # ... modify result ...
+      #     result
+      #   end
+      #
+
+      def apply(result, context = nil)
+        raise NotImplementedError, "#{self.class} must implement #apply"
+      end
+
+
+      # Check if this behavior should be applied
+      #
+      # Uses probability-based activation. If value is an Integer,
+      # it's treated as a percentage probability. If nil or >= 100,
+      # always applies.
+      #
+      # @return [Boolean] true if the behavior should be applied
+      #
+      # @example Probability check
+      #   behavior = Failure.new(10, rng)  # 10% probability
+      #   behavior.should_apply?  # => true (10% of the time)
+      #
+
+      def should_apply?
+        probability = extract_probability
+
+        # Always apply if no probability specified or 100%+
+        return true if probability.nil? || probability >= 100
+
+
+        # Use RNG for deterministic tests, or rand() otherwise
+        if rng
+          rng.rand(100) < probability
+        else
+          rand(100) < probability
+        end
+      end
+
+      private
+
+
+      # Extract probability from the value configuration
+      #
+      # @return [Integer, nil] probability percentage (0-100) or nil
+      #
+
+      def extract_probability
+        case value
+        when Integer then value
+        when Hash then value[:probability] || value[:percent]
+        else nil
+        end
+      end
+    end
+  end
+end

data/lib/synthra/behaviors/close_connection.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Close Connection Behavior
+# =============================================================================
+#
+# Simulates connection drops by raising SimulatedConnectionDrop exception.
+# Useful for testing error handling and retry logic.
+#
+# @example DSL usage
+#   User:
+#     @close_connection 5%           # 5% chance of connection drop
+#     name: name
+#     email: email
+#
+# =============================================================================
+
+
+module Synthra
+  module Behaviors
+
+    # Close connection behavior - simulates connection drop
+    #
+    # Raises SimulatedConnectionDrop exception when activated, simulating
+    # a network connection failure.
+    #
+    # @example Apply close connection behavior
+    #   behavior = CloseConnection.new(5, rng)  # 5% probability
+    #   begin
+    #     behavior.apply({ "name" => "John" })
+    #   rescue SimulatedConnectionDrop => e
+    #     # Handle connection drop
+    #   end
+    #
+
+    class CloseConnection < Base
+
+      # Apply close connection behavior
+      #
+      # Raises SimulatedConnectionDrop if the behavior should be applied
+      # based on probability.
+      #
+      # @param result [Object] generated data (not modified)
+      # @param context [Generator::Context, nil] generation context (not used)
+      # @return [Object] result (if behavior not applied)
+      # @raise [SimulatedConnectionDrop] if behavior activates
+      #
+
+      def apply(result, context = nil)
+        if should_apply?
+          probability = extract_probability
+          raise SimulatedConnectionDrop.new(probability: probability)
+        end
+        result
+      end
+    end
+  end
+end
+

data/lib/synthra/behaviors/deprecated.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Deprecated Behavior
+# =============================================================================
+#
+# The Deprecated behavior emits warnings when a schema or field is generated.
+# This helps teams track usage of deprecated schemas and plan migrations.
+#
+# @example Schema-level deprecation
+#   LegacyUser:
+#     @deprecated "Use User schema instead (v2.0)"
+#     id: uuid
+#     name: text
+#
+# @example Field-level deprecation (in behaviors)
+#   User:
+#     @deprecated "This schema will be removed in v3.0"
+#     old_id: id_sequence
+#     id: uuid
+#
+# =============================================================================
+
+
+# :nocov:
+module Synthra
+  module Behaviors
+
+    # Emits deprecation warnings during data generation
+    #
+    # The Deprecated behavior is used to mark schemas as deprecated.
+    # When data is generated from a deprecated schema, a warning is
+    # logged/printed to alert developers.
+    #
+    # @example DSL usage
+    #   OldSchema:
+    #     @deprecated "Use NewSchema instead"
+    #     field: text
+    #
+    # @example Programmatic check
+    #   behavior = Deprecated.new("Use NewSchema instead")
+    #   behavior.apply(result, context)  # Prints warning
+    #
+
+    class Deprecated < Base
+
+      # Apply the deprecation warning
+      #
+      # Emits a warning message about the deprecated schema.
+      # The warning is sent to Synthra.logger if available,
+      # otherwise to $stderr.
+      #
+      # @param result [Object] the generated data (passed through unchanged)
+      # @param context [Generator::Context, nil] generation context
+      # @return [Object] the unchanged result
+      #
+
+      def apply(result, context = nil)
+        emit_warning(context)
+        result
+      end
+
+      private
+
+
+      # Emit the deprecation warning
+      #
+      # @param context [Generator::Context, nil] generation context
+      # @return [void]
+      #
+
+      def emit_warning(context)
+        schema_name = context&.instance_variable_get(:@schema_name) || "Unknown"
+        message = build_warning_message(schema_name)
+
+        if Synthra.configuration.logger
+          Synthra.configuration.logger.warn(message)
+        else
+          warn "[Synthra] #{message}"
+        end
+      end
+
+
+      # Build the warning message
+      #
+      # @param schema_name [String] name of the deprecated schema
+      # @return [String] formatted warning message
+      #
+
+      def build_warning_message(schema_name)
+        deprecation_note = value.is_a?(String) ? value : "This schema is deprecated"
+        
+        "DEPRECATED: Schema '#{schema_name}' - #{deprecation_note}"
+      end
+    end
+  end
+end
+# :nocov:
+

data/lib/synthra/behaviors/failure.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Failure Behavior
+# =============================================================================
+#
+# Simulates service failures by raising SimulatedFailure errors.
+# Useful for testing error handling and retry logic in applications.
+#
+# @example DSL usage
+#   API:
+#     @failure 10%           # 10% chance of failure
+#     @failure 5             # Same as 5%
+#     id: uuid
+#
+# @example Testing error handling
+#   begin
+#     api_schema.generate
+#   rescue Synthra::SimulatedFailure => e
+#     # Test that your app handles failures correctly
+#   end
+#
+# =============================================================================
+
+
+module Synthra
+  module Behaviors
+
+    # Failure behavior - simulates service failure
+    #
+    # Raises a SimulatedFailure error based on configured probability.
+    # This is useful for testing how applications handle service
+    # unavailability, timeouts, and other failure scenarios.
+    #
+    # @example Create with probability
+    #   failure = Failure.new(10, rng)  # 10% failure rate
+    #   failure.apply(result)  # May raise SimulatedFailure
+    #
+
+    class Failure < Base
+
+      # Apply the failure behavior
+      #
+      # Based on probability, either raises SimulatedFailure or
+      # returns the result unchanged.
+      #
+      # @param result [Object] the generated data
+      # @param context [Generator::Context, nil] generation context (not used)
+      # @return [Object] the result if no failure
+      # @raise [SimulatedFailure] if failure is triggered
+      #
+      # @example
+      #   failure = Failure.new(10, rng)  # 10% failure rate
+      #   failure.apply({ "id" => "123" })
+      #   # Returns result 90% of the time
+      #   # Raises SimulatedFailure 10% of the time
+      #
+
+      def apply(result, context = nil)
+        if should_apply?
+          probability = extract_probability
+          raise SimulatedFailure.new(probability: probability)
+        end
+        result
+      end
+    end
+  end
+end

data/lib/synthra/behaviors/latency.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Latency Behavior
+# =============================================================================
+#
+# Simulates network latency by adding delays to data generation.
+# Useful for testing how applications handle slow responses.
+#
+# @example DSL usage
+#   User:
+#     @latency 500                 # Fixed 500ms delay
+#     @latency 100..500ms          # Random delay between 100-500ms
+#     @latency min: 100, max: 500  # Same as above with named args
+#
+# =============================================================================
+
+
+module Synthra
+  module Behaviors
+
+    # Latency behavior - adds configurable delay to data generation
+    #
+    # Simulates network latency by sleeping for a specified duration.
+    # The delay can be fixed or randomized within a range.
+    #
+    # @example Fixed delay
+    #   latency = Latency.new(500, rng)
+    #   latency.apply(result)  # Sleeps for 500ms
+    #
+    # @example Random delay
+    #   latency = Latency.new(100..500, rng)
+    #   latency.apply(result)  # Sleeps for random 100-500ms
+    #
+
+    class Latency < Base
+
+      # Apply latency to the result
+      #
+      # Calculates the delay and sleeps for that duration.
+      # Validates against configured maximum latency limit.
+      #
+      # @param result [Object] the generated data (passed through unchanged)
+      # @param context [Generator::Context, nil] generation context (not used)
+      # @return [Object] the result unchanged
+      # @raise [LatencyLimitError] if delay exceeds max_latency_ms limit
+      #
+      # @example
+      #   latency = Latency.new(500, rng)
+      #   result = latency.apply({ "id" => "123" })
+      #   # Sleeps for 500ms, then returns result
+      #
+
+      def apply(result, context = nil)
+        return result unless should_apply?
+
+        delay = calculate_delay
+
+        # Validate against configured limits
+        Synthra.configuration.limits.validate_latency!(delay)
+
+        # Sleep for delay (convert ms to seconds)
+        sleep(delay / 1000.0)
+        result
+      end
+
+      private
+
+
+      # Calculate the delay in milliseconds
+      #
+      # Supports multiple value formats:
+      # - Range: random value within range
+      # - Hash: { min: X, max: Y } for range
+      # - Integer: fixed delay
+      #
+      # @return [Integer] delay in milliseconds
+      #
+
+      def calculate_delay
+        case value
+        when Range
+
+          # Random delay within range
+          rng ? rng.rand(value) : rand(value)
+        when Hash
+
+          # Named min/max arguments
+          min = value[:min] || 0
+          max = value[:max] || min
+          rng ? rng.int(min, max) : rand(min..max)
+        when Integer
+
+          # Fixed delay
+          value
+        else
+          0
+        end
+      end
+    end
+  end
+end