synthra 0.1.0

data/lib/synthra/limits.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Resource Limits
+# =============================================================================
+#
+# This file defines resource limits to prevent runaway generation scenarios
+# that could exhaust system resources. Limits include:
+#
+# - Maximum latency for @latency behaviors
+# - Maximum recursion depth for nested schemas
+# - Maximum array size for array fields
+#
+# Configure limits via Synthra.configuration.limits
+#
+# @example Configure limits
+#   Synthra.configure do |config|
+#     config.limits.max_latency_ms = 10000
+#     config.limits.max_recursion = 5
+#     config.limits.max_array_size = 100
+#   end
+#
+# =============================================================================
+
+
+module Synthra
+
+  # Resource limits to prevent runaway generation
+  #
+  # The Limits class provides configurable safety limits that prevent
+  # accidental resource exhaustion during data generation. Each limit
+  # has a default value and can be customized per application needs.
+  #
+  # Limits are validated during generation, and appropriate errors are
+  # raised when limits are exceeded.
+  #
+  # @example Access limits
+  #   limits = Synthra.configuration.limits
+  #   limits.max_latency_ms   # => 5000
+  #   limits.max_recursion    # => 10
+  #   limits.max_array_size   # => 1000
+  #
+  # @example Configure limits
+  #   Synthra.configure do |config|
+  #     config.limits.max_latency_ms = 10000   # Allow up to 10 second delays
+  #     config.limits.max_recursion = 3        # Limit nesting to 3 levels
+  #     config.limits.max_array_size = 50      # Limit arrays to 50 elements
+  #   end
+  #
+  # @example Handle limit errors
+  #   begin
+  #     schema.generate
+  #   rescue Synthra::LatencyLimitError => e
+  #     puts "Latency too high: #{e.requested}ms > #{e.max_allowed}ms"
+  #   rescue Synthra::RecursionLimitError => e
+  #     puts "Too deeply nested: #{e.depth} > #{e.max_allowed}"
+  #   rescue Synthra::ArraySizeLimitError => e
+  #     puts "Array too large: #{e.size} > #{e.max_allowed}"
+  #   end
+  #
+
+  class Limits
+
+    # Default maximum latency in milliseconds (5 seconds)
+    #
+    # This prevents behaviors from creating excessively long delays
+    # that could cause timeouts in tests.
+    #
+    # @return [Integer] default maximum latency in milliseconds
+    #
+
+    DEFAULT_MAX_LATENCY_MS = 5000
+
+
+    # Default maximum recursion depth (10 levels)
+    #
+    # This prevents infinite recursion when schemas reference each other.
+    # Most real-world schemas don't need more than 5-10 levels of nesting.
+    #
+    # @return [Integer] default maximum recursion depth
+    #
+
+    DEFAULT_MAX_RECURSION = 10
+
+
+    # Default maximum array size (1000 elements)
+    #
+    # This prevents generating extremely large arrays that could
+    # consume excessive memory or take too long to generate.
+    #
+    # @return [Integer] default maximum array elements
+    #
+
+    DEFAULT_MAX_ARRAY_SIZE = 1000
+
+
+    # Default maximum text length (10,000 characters)
+    #
+    # This prevents generating extremely long text strings that could
+    # consume excessive memory or cause performance issues.
+    #
+    # @return [Integer] default maximum text length in characters
+    #
+
+    DEFAULT_MAX_TEXT_LENGTH = 10_000
+
+
+    # @!attribute max_latency_ms
+    #   Maximum allowed latency for @latency behaviors
+    #   @return [Integer] maximum latency in milliseconds
+    #   @see LatencyLimitError raised when exceeded
+    #
+    # @example Allow longer delays for integration tests
+    #   limits.max_latency_ms = 30000  # 30 seconds
+    #
+
+    attr_accessor :max_latency_ms
+
+
+    # @!attribute max_recursion
+    #   Maximum allowed recursion depth for nested schemas
+    #   @return [Integer] maximum nesting depth
+    #   @see RecursionLimitError raised when exceeded
+    #
+    # @example Limit nesting for performance
+    #   limits.max_recursion = 3  # Only 3 levels of nesting
+    #
+
+    attr_accessor :max_recursion
+
+
+    # @!attribute max_array_size
+    #   Maximum allowed number of elements in generated arrays
+    #   @return [Integer] maximum array size
+    #   @see ArraySizeLimitError raised when exceeded
+    #
+    # @example Limit array sizes for memory
+    #   limits.max_array_size = 100  # Maximum 100 elements
+    #
+
+    attr_accessor :max_array_size
+
+
+    # @!attribute max_text_length
+    #   Maximum allowed length for generated text strings
+    #   @return [Integer] maximum text length in characters
+    #   @see TextLengthLimitError raised when exceeded
+    #
+    # @example Limit text length for memory
+    #   limits.max_text_length = 5000  # Maximum 5000 characters
+    #
+
+    attr_accessor :max_text_length
+
+
+    # Create a new Limits instance with default values
+    #
+    # @return [Limits] a new limits instance with defaults
+    #
+    # @example
+    #   limits = Synthra::Limits.new
+    #   limits.max_latency_ms  # => 5000
+    #   limits.max_recursion   # => 10
+    #   limits.max_array_size  # => 1000
+    #
+
+    def initialize
+      @max_latency_ms = DEFAULT_MAX_LATENCY_MS
+      @max_recursion = DEFAULT_MAX_RECURSION
+      @max_array_size = DEFAULT_MAX_ARRAY_SIZE
+      @max_text_length = DEFAULT_MAX_TEXT_LENGTH
+    end
+
+
+    # Validate that a latency value is within limits
+    #
+    # Checks if the requested latency (in milliseconds) is within
+    # the configured maximum. If not, raises a LatencyLimitError.
+    #
+    # @param ms [Integer] the latency value in milliseconds to validate
+    # @raise [LatencyLimitError] if ms exceeds max_latency_ms
+    # @return [void] returns nil if validation passes
+    #
+    # @example Valid latency
+    #   limits.validate_latency!(1000)  # => nil (1 second is OK)
+    #
+    # @example Invalid latency
+    #   limits.max_latency_ms = 5000
+    #   limits.validate_latency!(10000)
+    #   # => LatencyLimitError: Latency 10000ms exceeds maximum allowed 5000ms
+    #
+
+    def validate_latency!(ms)
+      return if ms <= max_latency_ms
+
+      raise LatencyLimitError.new(requested: ms, max_allowed: max_latency_ms)
+    end
+
+
+    # Validate that a recursion depth is within limits
+    #
+    # Checks if the current recursion depth is within the configured
+    # maximum. This is called during nested schema generation to prevent
+    # infinite recursion.
+    #
+    # @param depth [Integer] the current recursion depth to validate
+    # @raise [RecursionLimitError] if depth exceeds max_recursion
+    # @return [void] returns nil if validation passes
+    #
+    # @example Valid depth
+    #   limits.validate_recursion!(5)  # => nil (5 levels is OK)
+    #
+    # @example Invalid depth
+    #   limits.max_recursion = 10
+    #   limits.validate_recursion!(15)
+    #   # => RecursionLimitError: Recursion depth 15 exceeds maximum allowed 10
+    #
+
+    def validate_recursion!(depth)
+      return if depth < max_recursion
+
+      raise RecursionLimitError.new(depth: depth, max_allowed: max_recursion)
+    end
+
+
+    # Validate that an array size is within limits
+    #
+    # Checks if the requested array size is within the configured
+    # maximum. This prevents generating arrays with excessive elements
+    # that could exhaust memory.
+    #
+    # @param size [Integer] the array size to validate
+    # @raise [ArraySizeLimitError] if size exceeds max_array_size
+    # @return [void] returns nil if validation passes
+    #
+    # @example Valid size
+    #   limits.validate_array_size!(100)  # => nil (100 elements is OK)
+    #
+    # @example Invalid size
+    #   limits.max_array_size = 1000
+    #   limits.validate_array_size!(5000)
+    #   # => ArraySizeLimitError: Array size 5000 exceeds maximum allowed 1000
+    #
+
+    def validate_array_size!(size)
+      return if size <= max_array_size
+
+      raise ArraySizeLimitError.new(size: size, max_allowed: max_array_size)
+    end
+
+
+    # Validate that a text length is within limits
+    #
+    # Checks if the requested text length is within the configured
+    # maximum. This prevents generating text strings with excessive
+    # characters that could exhaust memory.
+    #
+    # @param length [Integer] the text length in characters to validate
+    # @raise [TextLengthLimitError] if length exceeds max_text_length
+    # @return [void] returns nil if validation passes
+    #
+    # @example Valid length
+    #   limits.validate_text_length!(1000)  # => nil (1000 chars is OK)
+    #
+    # @example Invalid length
+    #   limits.max_text_length = 10000
+    #   limits.validate_text_length!(20000)
+    #   # => TextLengthLimitError: Text length 20000 exceeds maximum allowed 10000
+    #
+
+    def validate_text_length!(length)
+      return if length <= max_text_length
+      # :nocov:
+      raise TextLengthLimitError.new(length: length, max_allowed: max_text_length)
+      # :nocov:
+    end
+  end
+end