quonfig 0.0.2

data/lib/quonfig/internal_logger.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Quonfig
+  # Internal logger for the Quonfig SDK
+  # Uses SemanticLogger if available, falls back to stdlib Logger
+  class InternalLogger
+    def initialize(klass)
+      @klass = klass
+      @level_sym = nil # Track the symbol level for consistency
+
+      if defined?(SemanticLogger)
+        @logger = create_semantic_logger
+        @using_semantic = true
+      else
+        @logger = create_stdlib_logger
+        @using_semantic = false
+      end
+
+      # Track all instances regardless of logger type
+      instances << self
+    end
+
+    # Log methods
+    def trace(message = nil, &block)
+      log_message(:trace, message, &block)
+    end
+
+    def debug(message = nil, &block)
+      log_message(:debug, message, &block)
+    end
+
+    def info(message = nil, &block)
+      log_message(:info, message, &block)
+    end
+
+    def warn(message = nil, &block)
+      log_message(:warn, message, &block)
+    end
+
+    def error(message = nil, &block)
+      log_message(:error, message, &block)
+    end
+
+    def fatal(message = nil, &block)
+      log_message(:fatal, message, &block)
+    end
+
+    def level
+      if @using_semantic
+        @logger.level
+      else
+        # Return the symbol level we tracked, or map from Logger constant
+        @level_sym || case @logger.level
+                     when Logger::DEBUG then :debug
+                     when Logger::INFO then :info
+                     when Logger::WARN then :warn
+                     when Logger::ERROR then :error
+                     when Logger::FATAL then :fatal
+                     else :warn
+                     end
+      end
+    end
+
+    def level=(new_level)
+      if @using_semantic
+        @logger.level = new_level
+      else
+        # Track the symbol level for consistency
+        @level_sym = new_level
+
+        # Map symbol to Logger constant
+        @logger.level = case new_level
+                       when :trace, :debug then Logger::DEBUG
+                       when :info then Logger::INFO
+                       when :warn then Logger::WARN
+                       when :error then Logger::ERROR
+                       when :fatal then Logger::FATAL
+                       else Logger::WARN
+                       end
+      end
+    end
+
+    # Our client outputs debug logging,
+    # but if you aren't using Quonfig logging this could be too chatty.
+    # If you aren't using the quonfig log filter, only log warn level and above
+    def self.using_quonfig_log_filter!
+      @@instances&.each do |logger|
+        logger.level = :trace
+      end
+    end
+
+    private
+
+    def create_semantic_logger
+      default_level = env_log_level || :warn
+      logger = SemanticLogger::Logger.new(@klass, default_level)
+
+      # Wrap to prevent recursion
+      class << logger
+        def log(log, message = nil, progname = nil, &block)
+          return if recurse_check[local_log_id]
+          recurse_check[local_log_id] = true
+          begin
+            super(log, message, progname, &block)
+          ensure
+            recurse_check[local_log_id] = false
+          end
+        end
+
+        def local_log_id
+          Thread.current.__id__
+        end
+
+        private
+
+        def recurse_check
+          @recurse_check ||= Concurrent::Map.new(initial_capacity: 2)
+        end
+      end
+
+      logger
+    end
+
+    def create_stdlib_logger
+      require 'logger'
+      # When using stdlib Logger (no SemanticLogger), write to $stderr only
+      # Tests use $logs for SemanticLogger-filtered output, not stdlib Logger
+      logger = Logger.new($stderr)
+
+      # When SemanticLogger is not available, default to :warn to match SemanticLogger behavior
+      default_level_sym = :warn
+      @level_sym = env_log_level || default_level_sym
+
+      logger.level = case @level_sym
+                    when :trace, :debug then Logger::DEBUG
+                    when :info then Logger::INFO
+                    when :warn then Logger::WARN
+                    when :error then Logger::ERROR
+                    when :fatal then Logger::FATAL
+                    else Logger::WARN
+                    end
+      logger.progname = @klass.to_s
+
+      # Use a custom formatter that mimics SemanticLogger format
+      # SemanticLogger format: "ClassName -- Message"
+      # This helps tests that expect SemanticLogger-style output
+      logger.formatter = proc do |severity, datetime, progname, msg|
+        "#{progname} -- #{msg}\n"
+      end
+
+      logger
+    end
+
+    def env_log_level
+      level_str = ENV['QUONFIG_LOG_CLIENT_BOOTSTRAP_LOG_LEVEL']
+      level_str&.downcase&.to_sym
+    end
+
+    def log_message(level, message, &block)
+      if @using_semantic
+        @logger.send(level, message, &block)
+      else
+        # stdlib Logger doesn't have trace
+        level = :debug if level == :trace
+        @logger.send(level, message || block&.call)
+      end
+    end
+
+    def instances
+      @@instances ||= []
+    end
+  end
+end

data/lib/quonfig/murmer3.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class Murmur3
+  ## MurmurHash3 was written by Austin Appleby, and is placed in the public
+  ## domain. The author hereby disclaims copyright to this source code.
+
+  MASK32 = 0xffffffff
+
+  def self.murmur3_32_rotl(x, r)
+    ((x << r) | (x >> (32 - r))) & MASK32
+  end
+
+  def self.murmur3_32_fmix(h)
+    h &= MASK32
+    h ^= h >> 16
+    h = (h * 0x85ebca6b) & MASK32
+    h ^= h >> 13
+    h = (h * 0xc2b2ae35) & MASK32
+    h ^ (h >> 16)
+  end
+
+  def self.murmur3_32__mmix(k1)
+    k1 = (k1 * 0xcc9e2d51) & MASK32
+    k1 = murmur3_32_rotl(k1, 15)
+    (k1 * 0x1b873593) & MASK32
+  end
+
+  def self.murmur3_32(str, seed = 0)
+    h1 = seed
+    numbers = str.unpack('V*C*')
+    tailn = str.length % 4
+    tail = numbers.slice!(numbers.size - tailn, tailn)
+    for k1 in numbers
+      h1 ^= murmur3_32__mmix(k1)
+      h1 = murmur3_32_rotl(h1, 13)
+      h1 = (h1 * 5 + 0xe6546b64) & MASK32
+    end
+
+    unless tail.empty?
+      k1 = 0
+      tail.reverse_each do |c1|
+        k1 = (k1 << 8) | c1
+      end
+      h1 ^= murmur3_32__mmix(k1)
+    end
+
+    h1 ^= str.length
+    murmur3_32_fmix(h1)
+  end
+end

data/lib/quonfig/options.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Quonfig
+  # Options passed to Quonfig::Client at construction time.
+  class Options
+    attr_reader :sdk_key
+    attr_reader :environment
+    attr_reader :api_urls
+    attr_reader :sse_api_urls
+    attr_reader :telemetry_destination
+    attr_reader :config_api_urls
+    attr_reader :on_no_default
+    attr_reader :initialization_timeout_sec
+    attr_reader :on_init_failure
+    attr_reader :collect_sync_interval
+    attr_reader :datadir
+    attr_reader :enable_sse
+    attr_reader :enable_polling
+    attr_reader :global_context
+    attr_accessor :is_fork
+
+    module ON_INITIALIZATION_FAILURE
+      RAISE = :raise
+      RETURN = :return
+    end
+
+    module ON_NO_DEFAULT
+      RAISE = :raise
+      RETURN_NIL = :return_nil
+    end
+
+    DEFAULT_MAX_PATHS = 1_000
+    DEFAULT_MAX_KEYS = 100_000
+    DEFAULT_MAX_EXAMPLE_CONTEXTS = 100_000
+    DEFAULT_MAX_EVAL_SUMMARIES = 100_000
+
+    DEFAULT_API_URLS = [
+      'https://primary.quonfig.com',
+    ].freeze
+
+    # Derive the SSE stream URL for a given API URL by prepending `stream.` to
+    # the hostname. Preserves scheme, port, and path.
+    #
+    #   derive_stream_url('https://primary.quonfig.com')
+    #     # => 'https://stream.primary.quonfig.com'
+    #   derive_stream_url('http://localhost:6550')
+    #     # => 'http://stream.localhost:6550'
+    def self.derive_stream_url(api_url)
+      uri = URI.parse(api_url)
+      uri.host = "stream.#{uri.host}" if uri.host
+      uri.to_s
+    end
+
+    private def init(
+      api_urls: nil,
+      sdk_key: ENV['QUONFIG_BACKEND_SDK_KEY'],
+      environment: ENV['QUONFIG_ENVIRONMENT'],
+      datadir: ENV['QUONFIG_DIR'],
+      enable_sse: true,
+      enable_polling: true,
+      on_no_default: ON_NO_DEFAULT::RAISE,
+      initialization_timeout_sec: 10,
+      on_init_failure: ON_INITIALIZATION_FAILURE::RAISE,
+      collect_max_paths: DEFAULT_MAX_PATHS,
+      collect_sync_interval: nil,
+      context_upload_mode: :periodic_example, # :periodic_example, :shapes_only, :none
+      context_max_size: DEFAULT_MAX_EVAL_SUMMARIES,
+      collect_evaluation_summaries: true,
+      collect_max_evaluation_summaries: DEFAULT_MAX_EVAL_SUMMARIES,
+      allow_telemetry_in_local_mode: false,
+      global_context: {}
+    )
+      @sdk_key = sdk_key
+      @environment = environment
+      @datadir = datadir
+      @enable_sse = enable_sse
+      @enable_polling = enable_polling
+      @on_no_default = on_no_default
+      @initialization_timeout_sec = initialization_timeout_sec
+      @on_init_failure = on_init_failure
+
+      @collect_max_paths = collect_max_paths
+      @collect_sync_interval = collect_sync_interval
+      @collect_evaluation_summaries = collect_evaluation_summaries
+      @collect_max_evaluation_summaries = collect_max_evaluation_summaries
+      @allow_telemetry_in_local_mode = allow_telemetry_in_local_mode
+      @is_fork = false
+      @global_context = global_context
+
+      # defaults that may be overridden by context_upload_mode
+      @collect_shapes = false
+      @collect_max_shapes = 0
+      @collect_example_contexts = false
+      @collect_max_example_contexts = 0
+
+      if ENV['QUONFIG_API_URLS'] && ENV['QUONFIG_API_URLS'].length > 0
+        api_urls = ENV['QUONFIG_API_URLS']
+      end
+
+      @api_urls = Array(api_urls || DEFAULT_API_URLS).map { |url| remove_trailing_slash(url) }
+
+      @sse_api_urls = @api_urls.map { |url| Quonfig::Options.derive_stream_url(url) }
+      @config_api_urls = @api_urls
+
+      @telemetry_destination = ENV['QUONFIG_TELEMETRY_URL'] || derive_telemetry_destination(@api_urls)
+
+      case context_upload_mode
+      when :none
+        # no context telemetry
+      when :periodic_example
+        @collect_example_contexts = true
+        @collect_max_example_contexts = context_max_size
+        @collect_shapes = true
+        @collect_max_shapes = context_max_size
+      when :shapes_only
+        @collect_shapes = true
+        @collect_max_shapes = context_max_size
+      else
+        raise "Unknown context_upload_mode #{context_upload_mode}. Please provide :periodic_example, :shapes_only, or :none."
+      end
+    end
+
+    def initialize(options = {})
+      init(**options)
+    end
+
+    # In datadir mode the SDK evaluates config from a local workspace and does
+    # not connect to the delivery service.
+    def local_only?
+      !@datadir.nil?
+    end
+
+    def datadir?
+      !@datadir.nil?
+    end
+
+    def collect_max_paths
+      return 0 unless telemetry_allowed?(true)
+
+      @collect_max_paths
+    end
+
+    def collect_max_shapes
+      return 0 unless telemetry_allowed?(@collect_shapes)
+
+      @collect_max_shapes
+    end
+
+    def collect_max_example_contexts
+      return 0 unless telemetry_allowed?(@collect_example_contexts)
+
+      @collect_max_example_contexts
+    end
+
+    def collect_max_evaluation_summaries
+      return 0 unless telemetry_allowed?(@collect_evaluation_summaries)
+
+      @collect_max_evaluation_summaries
+    end
+
+    def sdk_key_id
+      @sdk_key&.split('-')&.first
+    end
+
+    def for_fork
+      clone = self.clone
+      clone.is_fork = true
+      clone
+    end
+
+    private
+
+    def telemetry_allowed?(option)
+      option && (!local_only? || @allow_telemetry_in_local_mode)
+    end
+
+    def remove_trailing_slash(url)
+      url.end_with?('/') ? url[0..-2] : url
+    end
+
+    # Derive a telemetry URL from the configured api_urls by swapping the
+    # primary/secondary host prefix for `telemetry` on a *.quonfig.com host.
+    # Falls back to https://telemetry.quonfig.com if no URL matches.
+    def derive_telemetry_destination(api_urls)
+      api_urls.each do |api_url|
+        match = api_url.match(%r{\Ahttps?://(?:primary|secondary)\.([^/]*quonfig\.com)}i)
+        return "https://telemetry.#{match[1]}" if match
+      end
+      'https://telemetry.quonfig.com'
+    end
+  end
+end

data/lib/quonfig/periodic_sync.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Quonfig
+  module PeriodicSync
+    LOG = Quonfig::InternalLogger.new(self)
+
+    def sync
+      return if @data.size.zero?
+
+      LOG.debug "Syncing #{@data.size} items"
+
+      start_at_was = @start_at
+      @start_at = Quonfig::TimeHelpers.now_in_ms
+
+      flush(prepare_data, start_at_was)
+    end
+
+    def prepare_data
+      to_ship = @data.dup
+      @data.clear
+
+      on_prepare_data
+
+      to_ship
+    end
+
+    def on_prepare_data
+      # noop -- override as you wish
+    end
+
+    def post(url, data)
+      @client.post(url, data)
+    end
+
+    def instance_hash
+      @client.instance_hash
+    end
+
+    def start_periodic_sync(sync_interval)
+      @start_at = Quonfig::TimeHelpers.now_in_ms
+
+      @sync_interval = calculate_sync_interval(sync_interval)
+
+      Thread.new do
+        LOG.debug "Initialized #{@name} instance_hash=#{@client.instance_hash}"
+
+        loop do
+          sleep @sync_interval.call
+          sync
+        end
+      end
+    end
+
+    def pool
+      @pool ||= Concurrent::ThreadPoolExecutor.new(
+        fallback_policy: :discard,
+        max_queue: 5,
+        max_threads: 4,
+        min_threads: 1,
+        name: @name
+      )
+    end
+
+    private
+
+    def calculate_sync_interval(sync_interval)
+      if sync_interval.is_a?(Numeric)
+        proc { sync_interval }
+      else
+        sync_interval || ExponentialBackoff.new(initial_delay: 8, max_delay: 600, multiplier: 1.5)
+      end
+    end
+  end
+end

data/lib/quonfig/quonfig.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Quonfig
+  LOG = Quonfig::InternalLogger.new(self)
+  @@lock = Concurrent::ReadWriteLock.new
+
+  def self.init(options = Quonfig::Options.new)
+    unless @singleton.nil?
+      LOG.warn 'Quonfig already initialized.'
+      return @singleton
+    end
+
+    @@lock.with_write_lock do
+      @singleton = Quonfig::Client.new(options)
+    end
+  end
+
+  def self.fork
+    ensure_initialized
+    @@lock.with_write_lock { @singleton = @singleton.fork }
+  end
+
+  def self.get(key, default = NO_DEFAULT_PROVIDED, jit_context = NO_DEFAULT_PROVIDED)
+    ensure_initialized(key)
+    @singleton.get(key, default, jit_context)
+  end
+
+  def self.enabled?(feature_name, jit_context = NO_DEFAULT_PROVIDED)
+    ensure_initialized(feature_name)
+    @singleton.enabled?(feature_name, jit_context)
+  end
+
+  def self.with_context(properties, &block)
+    ensure_initialized
+    @singleton.with_context(properties, &block)
+  end
+
+  def self.instance
+    ensure_initialized
+    @singleton
+  end
+
+  def self.semantic_logger_filter(config_key:)
+    ensure_initialized
+    @singleton.semantic_logger_filter(config_key: config_key)
+  end
+
+  def self.defined?(key)
+    ensure_initialized(key)
+    @singleton.defined?(key)
+  end
+
+  def self.ensure_initialized(key = nil)
+    if !defined?(@singleton) || @singleton.nil?
+      raise Quonfig::Errors::UninitializedError.new(key)
+    end
+  end
+end

data/lib/quonfig/rate_limit_cache.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Quonfig
+  # A key-based rate limiter that considers a key to be fresh if it has been
+  # seen within the last `duration` seconds.
+  #
+  # This is used to rate limit the number of times we send a given context
+  # to the server.
+  #
+  # Because expected usage is to immediately `set` on a `fresh?` miss, we do
+  # not prune the data structure on `fresh?` calls. Instead, we manually invoke
+  # `prune` periodically from the cache consumer.
+  class RateLimitCache
+    attr_reader :data
+
+    def initialize(duration)
+      @data = Concurrent::Map.new
+      @duration = duration
+    end
+
+    def fresh?(key)
+      timestamp = @data[key]
+
+      return false unless timestamp
+      return false if Time.now.utc.to_i - timestamp > @duration
+
+      true
+    end
+
+    def set(key)
+      @data[key] = Time.now.utc.to_i
+    end
+
+    def prune
+      now = Time.now.utc.to_i
+      @data.each_pair do |key, (timestamp, _)|
+        @data.delete(key) if now - timestamp > @duration
+      end
+    end
+  end
+end

data/lib/quonfig/reason.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Quonfig
+  # Computes the *why* of an evaluation — the symbol that explains which code path
+  # selected the returned value. Mirrors sdk-node/src/reason.ts.
+  #
+  #   :DEFAULT     — config has no targeting rules; matched value is the static default
+  #   :RULE_MATCH  — at least one targeting rule exists on the config (the matched
+  #                  conditional may itself be ALWAYS_TRUE, but the *config* is targeted)
+  #   :SPLIT       — matched value came from a non-default weighted variant
+  #   :ERROR       — evaluation failed
+  #   :UNKNOWN     — unable to determine
+  module Reason
+    UNKNOWN    = :UNKNOWN
+    DEFAULT    = :DEFAULT
+    RULE_MATCH = :RULE_MATCH
+    SPLIT      = :SPLIT
+    ERROR      = :ERROR
+
+    module_function
+
+    def compute(config:, conditional_value:, weighted_value_index: nil)
+      return SPLIT if weighted_value_index && weighted_value_index.positive?
+      return RULE_MATCH if targeting_rules?(config)
+      return RULE_MATCH if non_always_true_criteria?(conditional_value)
+      DEFAULT
+    end
+
+    def targeting_rules?(config)
+      config.rows.any? do |row|
+        row.values.any? { |cv| non_always_true_criteria?(cv) }
+      end
+    end
+
+    def non_always_true_criteria?(conditional_value)
+      conditional_value.criteria.any? { |c| c.operator != :ALWAYS_TRUE }
+    end
+  end
+end

data/lib/quonfig/resolver.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Quonfig
+  # Public-API resolver: looks up a config by key in a ConfigStore and runs
+  # it through an Evaluator against a Context.
+  #
+  #   store     = Quonfig::ConfigStore.new(configs_hash)
+  #   evaluator = Quonfig::Evaluator.new(store)
+  #   resolver  = Quonfig::Resolver.new(store, evaluator)
+  #   result    = resolver.get('my.flag', context)
+  #
+  # Mirrors the sdk-node pattern so integration tests (qfg-dk6.22-24) can
+  # drive evaluation without constructing a full Client. For the full
+  # production read path (with config_loader, SSE updates, telemetry), see
+  # Quonfig::ConfigResolver — the two coexist during the JSON migration.
+  class Resolver
+    attr_reader :store, :evaluator
+    attr_accessor :project_env_id
+
+    def initialize(store, evaluator)
+      @store = store
+      @evaluator = evaluator
+    end
+
+    def raw(key)
+      @store.get(key)
+    end
+
+    def get(key, context = nil)
+      config = raw(key)
+      return nil unless config
+
+      @evaluator.evaluate_config(config, context, resolver: self)
+    end
+
+    # Integration shims for code that expects a ConfigResolver. Keep these
+    # narrow; the real ConfigResolver still owns the production hot path.
+    def symbolize_json_names?
+      false
+    end
+  end
+end