synthra 0.1.0

data/lib/synthra/generator/faker_adapter.rb

@@ -0,0 +1,425 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Faker Adapter
+# =============================================================================
+#
+# Wraps Faker calls to use per-instance Random instead of global state.
+# This ensures thread safety and deterministic generation per Engine instance.
+#
+# @example Usage in type generators
+#   faker = FakerAdapter.new(rng)
+#   name = faker.name
+#   email = faker.email
+#
+# =============================================================================
+
+
+module Synthra
+  module Generator
+
+    # Adapter for Faker that uses per-instance Random
+    #
+    # Wraps all Faker calls to use a specific Random instance instead of
+    # modifying global Faker::Config.random. This enables thread-safe
+    # concurrent generation with different seeds.
+    #
+    # @note Performance Consideration: All FakerAdapter instances share a
+    #   single class-level mutex to synchronize access to Faker's global state.
+    #   Under very high concurrency (100+ threads), Faker calls will serialize
+    #   through this mutex, creating a potential bottleneck. This is an
+    #   acceptable trade-off for correctness and thread safety. For typical
+    #   use cases (< 50 concurrent threads), the performance impact is negligible.
+    #
+    # @note Thread Safety: The mutex ensures that Faker::Config.random is
+    #   correctly set and restored for each call, preventing race conditions
+    #   in multi-threaded environments. Each Engine instance has its own
+    #   FakerAdapter with its own Random instance, ensuring deterministic
+    #   output per Engine.
+    #
+    # @example Create adapter with RNG
+    #   rng = RNG.new(42)
+    #   faker = FakerAdapter.new(rng)
+    #   faker.name  # => "John Smith" (deterministic with seed 42)
+    #
+
+    class FakerAdapter
+
+      # Global mutex for synchronizing Faker::Config.random access
+      # 
+      # This mutex ensures thread-safe access to Faker's global random state.
+      # All FakerAdapter instances share this mutex, which may cause some
+      # serialization under high concurrency, but ensures correctness.
+      #
+      # @api private
+
+      @mutex = Mutex.new
+
+      class << self
+        attr_reader :mutex
+      end
+
+
+      # Create a new FakerAdapter
+      #
+      # @param rng [RNG] the random number generator to use
+      #
+
+      def initialize(rng)
+        @rng = rng
+        @faker_random = Random.new(rng.seed)
+      end
+
+
+      # Generate a name using Faker
+      #
+      # @return [String] generated name
+      #
+
+      def name
+        with_faker_random { Faker::Name.name }
+      end
+
+
+      # Generate an email using Faker
+      #
+      # @return [String] generated email
+      #
+
+      def email
+        with_faker_random { Faker::Internet.email }
+      end
+
+
+      # Generate a phone number using Faker
+      #
+      # @return [String] generated phone number
+      #
+
+      def phone_number
+        with_faker_random { Faker::PhoneNumber.phone_number }
+      end
+
+
+      # Generate a URL using Faker
+      #
+      # @return [String] generated URL
+      #
+
+      def url
+        with_faker_random { Faker::Internet.url }
+      end
+
+
+      # Generate an IPv4 address using Faker
+      #
+      # @return [String] generated IPv4 address
+      #
+
+      def ip_v4_address
+        with_faker_random { Faker::Internet.ip_v4_address }
+      end
+
+
+      # Generate an IPv6 address using Faker
+      #
+      # @return [String] generated IPv6 address
+      #
+
+      def ip_v6_address
+        with_faker_random { Faker::Internet.ip_v6_address }
+      end
+
+
+      # Generate text characters using Faker
+      #
+      # @param number [Integer] number of characters to generate
+      # @param locale [Symbol] locale to use (e.g., :en, :ar, :es)
+      # @return [String] generated text
+      #
+
+      def characters(number:, locale: nil)
+        with_faker_random do
+          if locale && Faker::Config.respond_to?(:locale=)
+            original_locale = Faker::Config.locale
+            begin
+              Faker::Config.locale = locale
+              Faker::Lorem.characters(number: number)
+            rescue StandardError
+              # :nocov:
+              # If locale not supported, fallback to current locale
+              Faker::Lorem.characters(number: number)
+              # :nocov:
+            ensure
+              Faker::Config.locale = original_locale
+            end
+          else
+            Faker::Lorem.characters(number: number)
+          end
+        end
+      end
+
+
+      # Generate a country code using Faker
+      #
+      # @return [String] generated country code
+      #
+
+      def country_code
+        with_faker_random { Faker::Address.country_code }
+      end
+
+
+      # Generate a currency code using Faker
+      #
+      # @return [String] generated currency code
+      #
+
+      def currency_code
+        with_faker_random { Faker::Currency.code }
+      end
+
+
+      # Generate a zip code using Faker
+      #
+      # @return [String] generated zip code
+      #
+
+      def zip_code
+        with_faker_random { Faker::Address.zip_code }
+      end
+
+
+      # Generate a postcode using Faker
+      #
+      # @return [String] generated postcode
+      #
+
+      def postcode
+        with_faker_random { Faker::Address.postcode }
+      end
+
+
+      # Generate a date in the past using Faker
+      #
+      # @param days [Integer] number of days in the past
+      # @return [Date] generated date
+      #
+
+      def date_backward(days:)
+        with_faker_random { Faker::Date.backward(days: days) }
+      end
+
+
+      # Generate a date in the future using Faker
+      #
+      # @param days [Integer] number of days in the future
+      # @return [Date] generated date
+      #
+
+      def date_forward(days:)
+        with_faker_random { Faker::Date.forward(days: days) }
+      end
+
+
+      # Generate a time in the past using Faker
+      #
+      # @param days [Integer] number of days in the past
+      # @return [Time] generated time
+      #
+
+      def time_backward(days:)
+        with_faker_random { Faker::Time.backward(days: days) }
+      end
+
+
+      # Generate a gender using Faker
+      #
+      # @return [String] generated gender
+      #
+
+      def gender
+        with_faker_random { Faker::Gender.type }
+      end
+
+
+      # Generate a timezone using Faker
+      #
+      # @return [String] generated timezone
+      #
+
+      def time_zone
+        with_faker_random { Faker::Address.time_zone }
+      end
+
+
+      # Generate a first name using Faker
+      #
+      # @return [String] generated first name
+      #
+
+      def first_name
+        with_faker_random { Faker::Name.first_name }
+      end
+
+
+      # Generate a last name using Faker
+      #
+      # @return [String] generated last name
+      #
+
+      def last_name
+        with_faker_random { Faker::Name.last_name }
+      end
+
+
+      # Generate an airline name using Faker
+      #
+      # @return [String] generated airline name
+      #
+
+      def airline
+        with_faker_random { Faker::Airline.name }
+      end
+
+
+      # Generate a blood type using Faker
+      #
+      # @return [String] generated blood type
+      #
+
+      def blood_type
+        with_faker_random { Faker::Blood.type }
+      end
+
+
+      # Generate a city using Faker
+      #
+      # @return [String] generated city
+      #
+
+      def city
+        with_faker_random { Faker::Address.city }
+      end
+
+
+      # Generate a state using Faker
+      #
+      # @return [String] generated state
+      #
+
+      def state
+        with_faker_random { Faker::Address.state }
+      end
+
+
+      # Generate a street address using Faker
+      #
+      # @return [String] generated street address
+      #
+
+      def street_address
+        with_faker_random { Faker::Address.street_address }
+      end
+
+
+      # Generate a street name using Faker
+      #
+      # @return [String] generated street name
+      #
+
+      def street_name
+        with_faker_random { Faker::Address.street_name }
+      end
+
+
+      # Generate a company name using Faker
+      #
+      # @return [String] generated company name
+      #
+
+      def company_name
+        with_faker_random { Faker::Company.name }
+      end
+
+
+      # Generate a buzzword using Faker
+      #
+      # @return [String] generated buzzword
+      #
+
+      def buzzword
+        with_faker_random { Faker::Company.buzzword }
+      end
+
+
+      # Generate a catch phrase using Faker
+      #
+      # @return [String] generated catch phrase
+      #
+
+      def catch_phrase
+        with_faker_random { Faker::Company.catch_phrase }
+      end
+
+
+      # Generate a color using Faker
+      #
+      # @return [String] generated color
+      #
+
+      def color
+        with_faker_random { Faker::Commerce.color }
+      end
+
+
+      # Generate a female first name using Faker
+      #
+      # @return [String] generated female first name
+      #
+
+      def female_first_name
+        with_faker_random { Faker::Name.female_first_name }
+      end
+
+
+      # Generate a male first name using Faker
+      #
+      # @return [String] generated male first name
+      #
+
+      def male_first_name
+        with_faker_random { Faker::Name.male_first_name }
+      end
+
+      private
+
+
+      # Temporarily set Faker's random and execute block
+      #
+      # This method synchronizes access to Faker::Config.random to ensure
+      # thread safety. It saves the current random, sets ours, executes
+      # the block, then restores the original.
+      #
+      # @yield [] block to execute with our random
+      # @return [Object] result of block
+      #
+
+      def with_faker_random
+
+        # Use class-level mutex to synchronize access to global Faker state
+        self.class.mutex.synchronize do
+          old_random = Faker::Config.random
+          begin
+            Faker::Config.random = @faker_random
+            yield
+          ensure
+            Faker::Config.random = old_random
+          end
+        end
+      end
+    end
+  end
+end
+