quonfig 0.0.2

data/lib/quonfig/semantic_logger_filter.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Quonfig
+  # SemanticLogger filter that gates log output by a single Quonfig config
+  # whose rules target the logger via the +quonfig.logger-name+ context
+  # property.
+  #
+  # Usage:
+  #   filter = client.semantic_logger_filter(config_key: 'log-levels.my-app')
+  #   SemanticLogger.add_appender(io: $stdout, filter: filter)
+  #
+  # The filter normalizes the SemanticLogger logger name to dotted snake_case
+  # (e.g. +MyApp::Foo::Bar+ → +my_app.foo.bar+) and exposes it to the
+  # evaluator under +quonfig.logger-name+ so the customer's Quonfig config can
+  # discriminate per-logger via PROP_STARTS_WITH_ONE_OF / PROP_IS_ONE_OF
+  # rules. Lookup is O(1): one +client.get+ call per log line.
+  class SemanticLoggerFilter
+    LEVELS = {
+      trace: 0,
+      debug: 1,
+      info:  2,
+      warn:  3,
+      error: 4,
+      fatal: 5
+    }.freeze
+
+    LOGGER_NAME_CONTEXT_KEY = 'quonfig.logger-name'
+
+    def self.semantic_logger_loaded?
+      defined?(SemanticLogger)
+    end
+
+    def initialize(client, config_key:)
+      unless self.class.semantic_logger_loaded?
+        raise LoadError, "semantic_logger gem is required for Quonfig::SemanticLoggerFilter. Add `gem 'semantic_logger'` to your Gemfile."
+      end
+
+      @client = client
+      @config_key = config_key
+    end
+
+    # SemanticLogger filter contract: return true to emit, false to suppress.
+    # Missing config key → return true so SemanticLogger's static level decides.
+    def call(log)
+      configured = @client.get(@config_key, nil, context_for(log))
+      return true if configured.nil?
+
+      log_severity = LEVELS[log.level] || LEVELS[:debug]
+      min_severity = LEVELS[normalize_level(configured)] || LEVELS[:debug]
+      log_severity >= min_severity
+    end
+
+    # Normalize a SemanticLogger logger name to the dotted snake_case form
+    # the customer writes targeting rules against.
+    #   MyApp::Foo::Bar → my_app.foo.bar
+    #   HTMLParser      → html_parser
+    def normalize(name)
+      name.to_s
+          .gsub('::', '.')
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
+    end
+
+    private
+
+    def context_for(log)
+      { 'quonfig' => { 'logger-name' => normalize(log.name) } }
+    end
+
+    def normalize_level(level)
+      case level
+      when Symbol  then level.downcase
+      when String  then level.downcase.to_sym
+      when Integer
+        # LogLevel ints from old proto: 1=trace … 9=fatal. Best-effort map.
+        case level
+        when 1 then :trace
+        when 2 then :debug
+        when 3 then :info
+        when 5 then :warn
+        when 6 then :error
+        when 9 then :fatal
+        else :debug
+        end
+      else :debug
+      end
+    end
+  end
+end

data/lib/quonfig/semver.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+class SemanticVersion
+  include Comparable
+
+  SEMVER_PATTERN = /
+    ^
+    (?<major>0|[1-9]\d*)
+    \.
+    (?<minor>0|[1-9]\d*)
+    \.
+    (?<patch>0|[1-9]\d*)
+    (?:-(?<prerelease>
+      (?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)
+      (?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*
+    ))?
+    (?:\+(?<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?
+    $
+  /x
+
+  attr_reader :major, :minor, :patch, :prerelease, :build_metadata
+
+  def self.parse(version_string)
+    raise ArgumentError, "version string cannot be nil" if version_string.nil?
+    raise ArgumentError, "version string cannot be empty" if version_string.empty?
+
+    match = SEMVER_PATTERN.match(version_string)
+    raise ArgumentError, "invalid semantic version format: #{version_string}" unless match
+
+    new(
+      major: match[:major].to_i,
+      minor: match[:minor].to_i,
+      patch: match[:patch].to_i,
+      prerelease: match[:prerelease],
+      build_metadata: match[:buildmetadata]
+    )
+  end
+
+  def self.parse_quietly(version_string)
+    parse(version_string)
+  rescue ArgumentError
+    nil
+  end
+
+  def initialize(major:, minor:, patch:, prerelease: nil, build_metadata: nil)
+    @major = major
+    @minor = minor
+    @patch = patch
+    @prerelease = prerelease
+    @build_metadata = build_metadata
+  end
+
+  def <=>(other)
+    return nil unless other.is_a?(SemanticVersion)
+
+    # Compare major.minor.patch
+    return major <=> other.major if major != other.major
+    return minor <=> other.minor if minor != other.minor
+    return patch <=> other.patch if patch != other.patch
+
+    # Compare pre-release versions
+    compare_prerelease(prerelease, other.prerelease)
+  end
+
+  def ==(other)
+    return false unless other.is_a?(SemanticVersion)
+
+    major == other.major &&
+      minor == other.minor &&
+      patch == other.patch &&
+      prerelease == other.prerelease
+    # Build metadata is ignored in equality checks
+  end
+
+  def eql?(other)
+    self == other
+  end
+
+  def hash
+    [major, minor, patch, prerelease].hash
+  end
+
+  def to_s
+    result = "#{major}.#{minor}.#{patch}"
+    result += "-#{prerelease}" if prerelease
+    result += "+#{build_metadata}" if build_metadata
+    result
+  end
+
+  private
+
+  def self.numeric?(str)
+    str.to_i.to_s == str
+  end
+
+  def compare_prerelease(pre1, pre2)
+    # If both are empty, they're equal
+    return 0 if pre1.nil? && pre2.nil?
+
+    # A version without prerelease has higher precedence
+    return 1 if pre1.nil?
+    return -1 if pre2.nil?
+
+    # Split into identifiers
+    ids1 = pre1.split('.')
+    ids2 = pre2.split('.')
+
+    # Compare each identifier until we find a difference
+    [ids1.length, ids2.length].min.times do |i|
+      cmp = compare_prerelease_identifiers(ids1[i], ids2[i])
+      return cmp if cmp != 0
+    end
+
+    # If all identifiers match up to the length of the shorter one,
+    # the longer one has higher precedence
+    ids1.length <=> ids2.length
+  end
+
+  def compare_prerelease_identifiers(id1, id2)
+    # If both are numeric, compare numerically
+    if self.class.numeric?(id1) && self.class.numeric?(id2)
+      return id1.to_i <=> id2.to_i
+    end
+
+    # If only one is numeric, numeric ones have lower precedence
+    return -1 if self.class.numeric?(id1)
+    return 1 if self.class.numeric?(id2)
+
+    # Neither is numeric, compare as strings
+    id1 <=> id2
+  end
+end

data/lib/quonfig/sse_config_client.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+require 'base64'
+require 'json'
+
+module Quonfig
+  class SSEConfigClient
+    class Options
+      attr_reader :sse_read_timeout, :seconds_between_new_connection,
+                  :sse_default_reconnect_time, :sleep_delay_for_new_connection_check,
+                  :errors_to_close_connection
+
+      def initialize(sse_read_timeout: 300,
+                     seconds_between_new_connection: 5,
+                     sleep_delay_for_new_connection_check: 1,
+                     sse_default_reconnect_time: SSE::Client::DEFAULT_RECONNECT_TIME,
+                     errors_to_close_connection: [HTTP::ConnectionError])
+        @sse_read_timeout = sse_read_timeout
+        @seconds_between_new_connection = seconds_between_new_connection
+        @sse_default_reconnect_time = sse_default_reconnect_time
+        @sleep_delay_for_new_connection_check = sleep_delay_for_new_connection_check
+        @errors_to_close_connection = errors_to_close_connection
+      end
+    end
+
+    LOG = Quonfig::InternalLogger.new(self)
+
+    def initialize(prefab_options, config_loader, options = nil, logger = nil)
+      @prefab_options = prefab_options
+      @options = options || Options.new
+      @config_loader = config_loader
+      @connected = false
+      @logger = logger || LOG
+    end
+
+    def close
+      @retry_thread&.kill
+      @client&.close
+    end
+
+    def start(&load_configs)
+      if @prefab_options.sse_api_urls.empty?
+        @logger.debug 'No SSE api_urls configured'
+        return
+      end
+
+      @client = connect(&load_configs)
+
+      closed_count = 0
+
+      @retry_thread = Thread.new do
+        loop do
+          sleep @options.sleep_delay_for_new_connection_check
+
+          if @client.closed?
+            closed_count += @options.sleep_delay_for_new_connection_check
+
+            if closed_count > @options.seconds_between_new_connection
+              closed_count = 0
+              @logger.debug 'Reconnecting SSE client'
+              @client = connect(&load_configs)
+            end
+          end
+        end
+      end
+    end
+
+    def connect(&load_configs)
+      url = "#{source}/api/v2/sse/config"
+      @logger.debug "SSE Streaming Connect to #{url} start_at #{@config_loader.highwater_mark}"
+
+      SSE::Client.new(url,
+                      headers: headers,
+                      read_timeout: @options.sse_read_timeout,
+                      reconnect_time: @options.sse_default_reconnect_time,
+                      last_event_id: (@config_loader.highwater_mark&.positive? ? @config_loader.highwater_mark.to_s : nil),
+                      logger: Quonfig::InternalLogger.new(SSE::Client)) do |client|
+        client.on_event do |event|
+          if event.data.nil? || event.data.empty?
+            @logger.error "SSE Streaming Error: Received empty data for url #{url}"
+            client.close
+            return
+          end
+
+          begin
+            parsed = JSON.parse(event.data)
+          rescue JSON::ParserError => e
+            @logger.error "SSE Streaming Error: Failed to parse JSON for url #{url}: #{e.message}"
+            client.close
+            return
+          end
+
+          envelope = Quonfig::ConfigEnvelope.new(
+            configs: parsed['configs'] || [],
+            meta: parsed['meta'] || {}
+          )
+          load_configs.call(envelope, event, :sse)
+        end
+
+        client.on_error do |error|
+          # SSL "unexpected eof" is expected when SSE sessions timeout normally
+          if error.is_a?(OpenSSL::SSL::SSLError) && error.message.include?('unexpected eof')
+            @logger.debug "SSE Streaming: Connection closed (expected timeout) for url #{url}"
+          else
+            @logger.error "SSE Streaming Error: #{error.inspect} for url #{url}"
+          end
+
+          if @options.errors_to_close_connection.any? { |klass| error.is_a?(klass) }
+            @logger.debug "Closing SSE connection for url #{url}"
+            client.close
+          end
+        end
+      end
+    end
+
+    def headers
+      auth = "1:#{@prefab_options.sdk_key}"
+      auth_string = Base64.strict_encode64(auth)
+      return {
+        'Authorization' => "Basic #{auth_string}",
+        'Accept' => 'text/event-stream',
+        'X-Quonfig-SDK-Version' => "sdk-ruby-#{Quonfig::VERSION}"
+      }
+    end
+
+    def source
+      @source_index = @source_index.nil? ? 0 : @source_index + 1
+
+      if @source_index >= @prefab_options.sse_api_urls.size
+        @source_index = 0
+      end
+
+      @prefab_options.sse_api_urls[@source_index]
+    end
+  end
+end

data/lib/quonfig/time_helpers.rb

@@ -0,0 +1,7 @@
+module Quonfig
+  module TimeHelpers
+    def self.now_in_ms
+      ::Time.now.utc.to_i * 1000
+    end
+  end
+end

data/lib/quonfig/types.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Ruby types mirroring the JSON delivery protocol defined in
+# sdk-node/src/types.ts. Field names are snake_case per Ruby convention;
+# callers parsing JSON fixtures (camelCase) are responsible for the mapping.
+# All Structs use keyword_init so omitted fields default to nil.
+module Quonfig
+  Value = Struct.new(:type, :value, :confidential, :decrypt_with, keyword_init: true)
+
+  Criterion = Struct.new(:property_name, :operator, :value_to_match, keyword_init: true)
+
+  Rule = Struct.new(:criteria, :value, keyword_init: true)
+
+  RuleSet = Struct.new(:rules, keyword_init: true)
+
+  Environment = Struct.new(:id, :rules, keyword_init: true)
+
+  Meta = Struct.new(:version, :environment, :workspace_id, keyword_init: true)
+
+  ConfigResponse = Struct.new(
+    :id,
+    :key,
+    :type,
+    :value_type,
+    :send_to_client_sdk,
+    :default,
+    :environment,
+    keyword_init: true
+  )
+
+  WeightedValue = Struct.new(:weight, :value, keyword_init: true)
+
+  WeightedValuesData = Struct.new(:weighted_values, :hash_by_property_name, keyword_init: true)
+
+  SchemaData = Struct.new(:schema_type, :schema, keyword_init: true)
+
+  ProvidedData = Struct.new(:source, :lookup, keyword_init: true)
+
+  WorkspaceEnvironment = Struct.new(:id, :rules, keyword_init: true)
+
+  WorkspaceConfigDocument = Struct.new(
+    :id,
+    :key,
+    :type,
+    :value_type,
+    :send_to_client_sdk,
+    :default,
+    :environments,
+    keyword_init: true
+  )
+
+  QuonfigDatadirEnvironments = Struct.new(:environments, keyword_init: true)
+
+  # ConfigEnvelope is already defined in lib/quonfig/config_envelope.rb with
+  # the same members (:configs, :meta). It is required from lib/quonfig.rb.
+end

data/lib/quonfig/weighted_value_resolver.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Quonfig
+  class WeightedValueResolver
+    MAX_32_FLOAT = 4_294_967_294.0
+
+    def initialize(weights, config_key, context_hash_value)
+      @weights = weights
+      @config_key = config_key
+      @context_hash_value = context_hash_value
+    end
+
+    def resolve
+      percent = @context_hash_value ? user_percent : rand
+
+      index = variant_index(percent)
+
+      [@weights[index], index]
+    end
+
+    def user_percent
+      to_hash = "#{@config_key}#{@context_hash_value}"
+      int_value = Murmur3.murmur3_32(to_hash)
+      int_value / MAX_32_FLOAT
+    end
+
+    def variant_index(percent_through_distribution)
+      distribution_space = @weights.inject(0) { |sum, v| sum + weight_of(v) }
+      bucket = distribution_space * percent_through_distribution
+
+      sum = 0
+      @weights.each_with_index do |variant, index|
+        w = weight_of(variant)
+        return index if bucket < sum + w
+
+        sum += w
+      end
+
+      # In the event that all weights are zero, return the last variant
+      @weights.size - 1
+    end
+
+    private
+
+    def weight_of(variant)
+      variant[:weight] || variant['weight']
+    end
+  end
+end

data/lib/quonfig.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Quonfig
+  NO_DEFAULT_PROVIDED = :no_default_provided
+  VERSION = File.read(File.dirname(__FILE__) + '/../VERSION').strip
+end
+
+begin
+  require 'semantic_logger'
+rescue LoadError
+  # semantic_logger is optional - only needed for dynamic log level filtering
+end
+
+require 'securerandom'
+require 'concurrent/atomics'
+require 'concurrent'
+require 'faraday'
+require 'openssl'
+require 'ld-eventsource'
+
+require 'quonfig/internal_logger'
+require 'quonfig/time_helpers'
+require 'quonfig/types'
+require 'quonfig/error'
+require 'quonfig/duration'
+require 'quonfig/reason'
+require 'quonfig/evaluation'
+require 'quonfig/encryption'
+require 'quonfig/exponential_backoff'
+require 'quonfig/periodic_sync'
+require 'quonfig/errors/initialization_timeout_error'
+require 'quonfig/errors/invalid_sdk_key_error'
+require 'quonfig/errors/missing_default_error'
+require 'quonfig/errors/env_var_parse_error'
+require 'quonfig/errors/missing_env_var_error'
+require 'quonfig/errors/type_mismatch_error'
+require 'quonfig/errors/uninitialized_error'
+require 'quonfig/options'
+require 'quonfig/rate_limit_cache'
+require 'quonfig/weighted_value_resolver'
+require 'quonfig/config_store'
+require 'quonfig/evaluator'
+require 'quonfig/resolver'
+require 'quonfig/config_envelope'
+require 'quonfig/config_loader'
+require 'quonfig/datadir'
+require 'quonfig/sse_config_client'
+require 'quonfig/http_connection'
+require 'quonfig/caching_http_connection'
+require 'quonfig/context'
+require 'quonfig/client'
+require 'quonfig/bound_client'
+require 'quonfig/semantic_logger_filter'
+require 'quonfig/quonfig'
+require 'quonfig/murmer3'
+require 'quonfig/semver'
+require 'quonfig/fixed_size_hash'

data/quonfig.gemspec

@@ -0,0 +1,149 @@
+# Generated by juwelier
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Juwelier::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+# stub: quonfig 0.0.2 ruby lib
+
+Gem::Specification.new do |s|
+  s.name = "quonfig".freeze
+  s.version = "0.0.2".freeze
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
+  s.require_paths = ["lib".freeze]
+  s.authors = ["Jeff Dwyer".freeze]
+  s.date = "2026-04-22"
+  s.description = "Quonfig \u2014 feature flags and live config, stored as files in git.".freeze
+  s.email = "jeff@quonfig.com".freeze
+  s.extra_rdoc_files = [
+    "CHANGELOG.md",
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    ".claude/rules/constitution.md",
+    ".claude/rules/git-safety.md",
+    ".claude/rules/issue-tracking.md",
+    ".claude/rules/testing-workflow.md",
+    ".envrc.sample",
+    ".github/CODEOWNERS",
+    ".github/pull_request_template.md",
+    ".github/workflows/push_gem.yml",
+    ".github/workflows/ruby.yml",
+    ".github/workflows/test.yaml",
+    ".rubocop.yml",
+    ".tool-versions",
+    "CHANGELOG.md",
+    "CLAUDE.md",
+    "CODEOWNERS",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "dev/allocation_stats",
+    "dev/benchmark",
+    "dev/console",
+    "dev/script_setup.rb",
+    "lib/quonfig.rb",
+    "lib/quonfig/bound_client.rb",
+    "lib/quonfig/caching_http_connection.rb",
+    "lib/quonfig/client.rb",
+    "lib/quonfig/config_envelope.rb",
+    "lib/quonfig/config_loader.rb",
+    "lib/quonfig/config_store.rb",
+    "lib/quonfig/context.rb",
+    "lib/quonfig/datadir.rb",
+    "lib/quonfig/duration.rb",
+    "lib/quonfig/encryption.rb",
+    "lib/quonfig/error.rb",
+    "lib/quonfig/errors/env_var_parse_error.rb",
+    "lib/quonfig/errors/initialization_timeout_error.rb",
+    "lib/quonfig/errors/invalid_sdk_key_error.rb",
+    "lib/quonfig/errors/missing_default_error.rb",
+    "lib/quonfig/errors/missing_env_var_error.rb",
+    "lib/quonfig/errors/type_mismatch_error.rb",
+    "lib/quonfig/errors/uninitialized_error.rb",
+    "lib/quonfig/evaluation.rb",
+    "lib/quonfig/evaluator.rb",
+    "lib/quonfig/exponential_backoff.rb",
+    "lib/quonfig/fixed_size_hash.rb",
+    "lib/quonfig/http_connection.rb",
+    "lib/quonfig/internal_logger.rb",
+    "lib/quonfig/murmer3.rb",
+    "lib/quonfig/options.rb",
+    "lib/quonfig/periodic_sync.rb",
+    "lib/quonfig/quonfig.rb",
+    "lib/quonfig/rate_limit_cache.rb",
+    "lib/quonfig/reason.rb",
+    "lib/quonfig/resolver.rb",
+    "lib/quonfig/semantic_logger_filter.rb",
+    "lib/quonfig/semver.rb",
+    "lib/quonfig/sse_config_client.rb",
+    "lib/quonfig/time_helpers.rb",
+    "lib/quonfig/types.rb",
+    "lib/quonfig/weighted_value_resolver.rb",
+    "quonfig.gemspec",
+    "scripts/generate_integration_tests.rb",
+    "test/fixtures/datafile.json",
+    "test/integration/test_context_precedence.rb",
+    "test/integration/test_datadir_environment.rb",
+    "test/integration/test_enabled.rb",
+    "test/integration/test_enabled_with_contexts.rb",
+    "test/integration/test_get.rb",
+    "test/integration/test_get_feature_flag.rb",
+    "test/integration/test_get_or_raise.rb",
+    "test/integration/test_get_weighted_values.rb",
+    "test/integration/test_helpers.rb",
+    "test/integration/test_helpers_test.rb",
+    "test/integration/test_post.rb",
+    "test/integration/test_telemetry.rb",
+    "test/support/common_helpers.rb",
+    "test/support/mock_base_client.rb",
+    "test/support/mock_config_loader.rb",
+    "test/test_bound_client.rb",
+    "test/test_caching_http_connection.rb",
+    "test/test_client.rb",
+    "test/test_config_loader.rb",
+    "test/test_context.rb",
+    "test/test_datadir.rb",
+    "test/test_duration.rb",
+    "test/test_encryption.rb",
+    "test/test_evaluator.rb",
+    "test/test_exponential_backoff.rb",
+    "test/test_fixed_size_hash.rb",
+    "test/test_helper.rb",
+    "test/test_http_connection.rb",
+    "test/test_internal_logger.rb",
+    "test/test_options.rb",
+    "test/test_rate_limit_cache.rb",
+    "test/test_reason.rb",
+    "test/test_rename.rb",
+    "test/test_resolver.rb",
+    "test/test_semantic_logger_filter.rb",
+    "test/test_semver.rb",
+    "test/test_sse_config_client.rb",
+    "test/test_typed_getters.rb",
+    "test/test_types.rb",
+    "test/test_weighted_value_resolver.rb"
+  ]
+  s.homepage = "https://github.com/quonfig/sdk-ruby".freeze
+  s.licenses = ["MIT".freeze]
+  s.rubygems_version = "3.5.22".freeze
+  s.summary = "Quonfig Ruby SDK".freeze
+
+  s.specification_version = 4
+
+  s.add_runtime_dependency(%q<concurrent-ruby>.freeze, ["~> 1.0".freeze, ">= 1.0.5".freeze])
+  s.add_runtime_dependency(%q<faraday>.freeze, [">= 0".freeze])
+  s.add_runtime_dependency(%q<ld-eventsource>.freeze, [">= 0".freeze])
+  s.add_runtime_dependency(%q<uuid>.freeze, [">= 0".freeze])
+  s.add_runtime_dependency(%q<activesupport>.freeze, [">= 4".freeze])
+  s.add_development_dependency(%q<allocation_stats>.freeze, [">= 0".freeze])
+  s.add_development_dependency(%q<benchmark-ips>.freeze, [">= 0".freeze])
+  s.add_development_dependency(%q<bundler>.freeze, [">= 0".freeze])
+  s.add_development_dependency(%q<juwelier>.freeze, ["~> 2.4.9".freeze])
+  s.add_development_dependency(%q<rdoc>.freeze, [">= 0".freeze])
+  s.add_development_dependency(%q<simplecov>.freeze, [">= 0".freeze])
+end
+