quonfig 0.0.5 → 0.0.8

data/lib/quonfig/resolver.rb

@@ -14,6 +14,8 @@ module Quonfig
   # production read path (with config_loader, SSE updates, telemetry), see
   # Quonfig::ConfigResolver — the two coexist during the JSON migration.
   class Resolver
+    TRUE_VALUES = %w[true 1 t yes].freeze
+
     attr_reader :store, :evaluator
     attr_accessor :project_env_id
 
@@ -26,11 +28,55 @@ module Quonfig
       @store.get(key)
     end
 
+    # Look up +key+ and evaluate against +context+. Mirrors Quonfig.get_or_raise
+    # semantics: if the key is unknown to the store, raise
+    # Quonfig::Errors::MissingDefaultError so callers can distinguish "no
+    # such config" from "config matched a nil/false value". Tests that want
+    # the legacy "return nil if absent" shape can rescue and recover (see
+    # IntegrationTestHelpers.assert_resolved, which folds a missing-key
+    # raise into the test's expected default).
     def get(key, context = nil)
       config = raw(key)
-      return nil unless config
+      raise Quonfig::Errors::MissingDefaultError.new(key) if config.nil?
+
+      eval_result = @evaluator.evaluate_config(config, context, resolver: self)
+      return nil if eval_result.nil?
+
+      weighted_index = nil
+      resolved_value = resolve_value(eval_result.value, config, context) do |idx|
+        weighted_index = idx
+      end
+      EvalResult.new(
+        value: resolved_value,
+        rule_index: eval_result.rule_index,
+        config: config,
+        weighted_value_index: weighted_index
+      )
+    end
+
+    # Post-evaluation value resolution. Mirrors sdk-node Resolver#resolveValue
+    # and sdk-go resolver.Resolve:
+    # - "provided" + ENV_VAR  → read ENV[lookup], coerce to config's valueType
+    # - confidential + decryptWith → look up the key config, decrypt
+    # - everything else passes through unchanged
+    def resolve_value(value, config, context = nil, &on_weighted_index)
+      return nil if value.nil?
 
-      @evaluator.evaluate_config(config, context, resolver: self)
+      type = vget(value, :type, 'type')
+
+      if type == 'provided'
+        return resolve_provided(value, config)
+      end
+
+      if type == 'weighted_values'
+        return resolve_weighted(value, config, context, &on_weighted_index)
+      end
+
+      confidential = vget(value, :confidential, 'confidential')
+      decrypt_with = vget(value, :decryptWith, 'decryptWith', :decrypt_with, 'decrypt_with')
+      return resolve_decryption(value, config, context, decrypt_with) if confidential && decrypt_with && !decrypt_with.to_s.empty?
+
+      value
     end
 
     # Integration shims for code that expects a ConfigResolver. Keep these
@@ -38,5 +84,144 @@ module Quonfig
     def symbolize_json_names?
       false
     end
+
+    private
+
+    def vget(hash, *keys)
+      return nil if hash.nil?
+
+      keys.each do |k|
+        return hash[k] if hash.is_a?(Hash) && hash.key?(k)
+      end
+      nil
+    end
+
+    def config_key(config)
+      return nil if config.nil?
+
+      vget(config, :key, 'key')
+    end
+
+    def config_value_type(config)
+      return nil if config.nil?
+
+      vget(config, :value_type, 'value_type', 'valueType', :valueType)
+    end
+
+    def resolve_provided(value, config)
+      provided = vget(value, :value, 'value')
+      return value if provided.nil?
+
+      source = vget(provided, :source, 'source')
+      lookup = vget(provided, :lookup, 'lookup')
+      return value if source != 'ENV_VAR' || lookup.nil? || lookup.to_s.empty?
+
+      env_value = ENV[lookup.to_s]
+      if env_value.nil?
+        raise Quonfig::Errors::MissingEnvVarError,
+              %(Environment variable "#{lookup}" not set for config "#{config_key(config)}")
+      end
+
+      value_type = config_value_type(config)
+      coerced = coerce_env_value(env_value, value_type, config, lookup)
+      {
+        'type' => coerced_value_type(value_type),
+        'value' => coerced
+      }
+    end
+
+    # Pick a weighted variant. Mirrors sdk-node Resolver#resolveWeightedValues
+    # and sdk-go resolveWeightedValues: hash the configured context property
+    # (or fall back to a per-call random) into [0,1), then walk the variant
+    # weights until cumulative weight >= bucket. Recurses through
+    # resolve_value so nested provided/encrypted variants work too.
+    def resolve_weighted(value, config, context, &on_weighted_index)
+      payload = vget(value, :value, 'value') || {}
+      weighted = vget(payload, :weightedValues, 'weightedValues', :weighted_values, 'weighted_values')
+      return value unless weighted.is_a?(Array) && !weighted.empty?
+
+      hash_property = vget(payload, :hashByPropertyName, 'hashByPropertyName',
+                           :hash_by_property_name, 'hash_by_property_name')
+      hash_value = nil
+      if hash_property && context
+        ctx_value =
+          if context.respond_to?(:get)
+            context.get(hash_property.to_s)
+          elsif context.is_a?(Hash)
+            ctx_obj = Quonfig::Context.new(context)
+            ctx_obj.get(hash_property.to_s)
+          end
+        hash_value = ctx_value.to_s unless ctx_value.nil?
+      end
+
+      cfg_key = config_key(config)
+      picker = Quonfig::WeightedValueResolver.new(weighted, cfg_key, hash_value)
+      variant, index = picker.resolve
+      on_weighted_index&.call(index)
+      variant_value = vget(variant, :value, 'value')
+      resolve_value(variant_value, config, context, &on_weighted_index)
+    end
+
+    # Recursively resolve the decryption-key config (it may itself be a
+    # provided ENV_VAR), then AES-GCM decrypt the value with that key.
+    def resolve_decryption(value, config, context, decrypt_with)
+      key_cfg = @store.get(decrypt_with)
+      raise Quonfig::Error, %(Decryption key config "#{decrypt_with}" not found) if key_cfg.nil?
+
+      key_match = @evaluator.evaluate_config(key_cfg, context, resolver: self)
+      raise Quonfig::Error, %(Decryption key config "#{decrypt_with}" did not match) if key_match.nil?
+
+      resolved_key = resolve_value(key_match.value, key_cfg, context)
+      secret_key = vget(resolved_key, :value, 'value').to_s
+      raise Quonfig::Error, %(Decryption key from "#{decrypt_with}" is empty) if secret_key.empty?
+
+      ciphertext = vget(value, :value, 'value').to_s
+      begin
+        plaintext = Quonfig::Encryption.new(secret_key).decrypt(ciphertext)
+      rescue StandardError => e
+        raise Quonfig::Errors::DecryptionError.new(config_key(config), e.message)
+      end
+
+      {
+        'type' => 'string',
+        'value' => plaintext,
+        'confidential' => true
+      }
+    end
+
+    # Coerce a raw env var string to the SDK type declared by the config.
+    # Matches sdk-node coerceValue (string/int/double/bool/string_list)
+    # and sdk-go coerceValue (string/int/double/bool). Anything else falls
+    # through as a string.
+    def coerce_env_value(env_value, value_type, config, lookup)
+      case value_type
+      when 'string', nil, ''
+        env_value
+      when 'int'
+        Integer(env_value, 10)
+      when 'double'
+        Float(env_value)
+      when 'bool'
+        TRUE_VALUES.include?(env_value.downcase)
+      when 'string_list'
+        env_value.split(/\s*,\s*/)
+      when 'duration'
+        env_value
+      else
+        env_value
+      end
+    rescue ArgumentError, TypeError
+      raise Quonfig::Errors::EnvVarParseError.new(env_value, config, lookup)
+    end
+
+    def coerced_value_type(value_type)
+      case value_type
+      when 'int'         then 'int'
+      when 'double'      then 'double'
+      when 'bool'        then 'bool'
+      when 'string_list' then 'string_list'
+      else 'string'
+      end
+    end
   end
 end

data/lib/quonfig/stdlib_formatter.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Quonfig
+  # Adapter that plugs Quonfig's dynamic log-level evaluation into Ruby's
+  # built-in +::Logger+. The formatter is a proc with the stdlib Logger
+  # contract — +(severity, datetime, progname, msg) -> String+ — that calls
+  # +client.should_log?+ before each line and returns either a formatted
+  # record (emit) or an empty string (suppress).
+  #
+  # Returning an empty string is how you "drop" a log line through the
+  # formatter hook: +::Logger+ writes exactly what the formatter returns,
+  # so an empty string produces zero visible output. We deliberately do NOT
+  # return +nil+ — stdlib Logger would still call +.to_s+ (→ "") on some
+  # Ruby versions but would emit "\n" from +::Logger::Formatter+ subclasses
+  # that pre-wrap the message. Empty string is the portable zero-output
+  # sentinel.
+  #
+  # Usage:
+  #   client = Quonfig::Client.new(logger_key: 'log-level.my-app')
+  #   logger = ::Logger.new($stdout)
+  #   logger.formatter = client.stdlib_formatter           # progname wins
+  #   # or
+  #   logger.formatter = client.stdlib_formatter(logger_name: 'MyApp::Svc')
+  #
+  # +logger_name+ (optional) is the fallback when +progname+ is nil / the
+  # caller doesn't pass one to the individual log call. If both are set,
+  # +logger_name+ wins — matching ReforgeHQ's stdlib_formatter semantics.
+  #
+  # Level mapping (stdlib severity string → quonfig level symbol):
+  #
+  #   "DEBUG"   -> :debug
+  #   "INFO"    -> :info
+  #   "WARN"    -> :warn
+  #   "ERROR"   -> :error
+  #   "FATAL"   -> :fatal
+  #   "ANY"     -> :fatal  (Logger::UNKNOWN — treat as top severity)
+  #   other     -> :info   (defensive — unknown labels don't silently drop)
+  #
+  # No normalization is applied to +progname+ / +logger_name+; they are
+  # passed verbatim into +quonfig-sdk-logging.key+ so customer matching
+  # rules can target exact class names (e.g. +PROP_STARTS_WITH_ONE_OF
+  # "MyApp::Services::"+). Parallels the SemanticLoggerFilter.
+  module StdlibFormatter
+    # Ruby stdlib Logger severity strings → quonfig level symbols. Covers
+    # every label the stdlib actually emits.
+    SEVERITY_TO_LEVEL = {
+      'DEBUG' => :debug,
+      'INFO'  => :info,
+      'WARN'  => :warn,
+      'ERROR' => :error,
+      'FATAL' => :fatal,
+      'ANY'   => :fatal # Logger::UNKNOWN formats as "ANY"
+    }.freeze
+
+    # Build a formatter Proc. Exposed on +Quonfig::Client#stdlib_formatter+;
+    # callers should prefer the client helper.
+    #
+    # @param client [Quonfig::Client] the client whose +should_log?+ gates output.
+    # @param logger_name [String, nil] fallback logger identifier when the
+    #   Logger call-site doesn't supply a progname.
+    # @return [Proc] a (severity, datetime, progname, msg) → String proc.
+    def self.build(client, logger_name: nil)
+      unless client.logger_key
+        raise Quonfig::Error,
+              'logger_key must be set at init to use stdlib_formatter. ' \
+              'Pass `logger_key:` to Quonfig::Options.new, or call ' \
+              'semantic_logger_filter(config_key:) / get(config_key) directly.'
+      end
+
+      # Arity MUST be 4 — ::Logger invokes the formatter with exactly that
+      # signature. Declared explicitly (not *args) so arity is 4, matching
+      # ::Logger::Formatter#call.
+      proc do |severity, datetime, progname, msg|
+        path = logger_name || progname
+        level = SEVERITY_TO_LEVEL[severity.to_s.upcase] || :info
+
+        if client.should_log?(logger_path: path, desired_level: level)
+          format_record(severity, datetime, progname, msg)
+        else
+          ''
+        end
+      end
+    end
+
+    # Default record formatter. Matches ::Logger::Formatter's general shape
+    # ("I, [timestamp pid] SEVERITY -- progname: message") but without the
+    # process-id first-letter noise so output is readable in tests and
+    # modern dev logs. Callers who want a different format can wrap the
+    # gated proc with their own renderer.
+    def self.format_record(severity, datetime, progname, msg)
+      ts = datetime.respond_to?(:strftime) ? datetime.strftime('%Y-%m-%dT%H:%M:%S.%6N') : datetime.to_s
+      "[#{ts}] #{severity} -- #{progname}: #{msg}\n"
+    end
+  end
+end

data/lib/quonfig/telemetry/context_shape.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Quonfig
+  module Telemetry
+    # Maps a context property value to the numeric field-type code used by
+    # api-telemetry. The numbers match the codes used by sdk-node and sdk-go
+    # (and historically the Prefab proto ConfigValue oneof):
+    #
+    #   1  = integer
+    #   2  = string
+    #   4  = double (float)
+    #   5  = boolean
+    #   10 = string list (array)
+    class ContextShape
+      MAPPING = {
+        Integer => 1,
+        String => 2,
+        Float => 4,
+        TrueClass => 5,
+        FalseClass => 5,
+        Array => 10
+      }.freeze
+
+      # We default to 2 (String) for unknown types — criteria evaluation
+      # treats them as strings via #to_s.
+      DEFAULT = MAPPING[String]
+
+      def self.field_type_number(value)
+        MAPPING.fetch(value.class, DEFAULT)
+      end
+    end
+  end
+end

data/lib/quonfig/telemetry/context_shape_aggregator.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Quonfig
+  module Telemetry
+    # Aggregates the set of context shapes observed during config
+    # evaluation. Each unique (context-name, property, type) tuple is
+    # stored once. On sync, the set is folded into a hash grouped by
+    # context name and emitted as api-telemetry's `contextShapes` event.
+    #
+    # Matches the sdk-node/sdk-go JSON wire format — NOT the old
+    # Prefab protobuf serialization.
+    class ContextShapeAggregator
+      attr_reader :data
+
+      def initialize(max_shapes:)
+        @max_shapes = max_shapes
+        @data = Concurrent::Set.new
+      end
+
+      # Record every property of every named context in +context+.
+      # +context+ may be a Quonfig::Context or a bare Hash
+      # ({ 'user' => { 'key' => ..., 'email' => ... }, ... }).
+      def push(context)
+        return if @max_shapes <= 0
+        return if context.nil?
+        return if @data.size >= @max_shapes
+
+        each_named_context(context) do |name, hash|
+          next unless hash.is_a?(Hash)
+
+          hash.each_pair do |key, value|
+            next if @data.size >= @max_shapes
+
+            @data.add [name.to_s, key.to_s, Quonfig::Telemetry::ContextShape.field_type_number(value)]
+          end
+        end
+      end
+
+      # Fold the raw tuples into { name => { key => type, ... }, ... }.
+      # Clears the underlying set.
+      def prepare_data
+        duped = @data.dup
+        @data.clear
+
+        duped.inject({}) do |acc, (name, key, type)|
+          acc[name] ||= {}
+          acc[name][key] = type
+          acc
+        end
+      end
+
+      # Drain accumulated shapes into a single telemetry event payload,
+      # matching api-telemetry's ContextShapesSchema. Returns +nil+ when
+      # there is nothing to ship — the reporter should skip empty events.
+      def drain_event
+        return nil if @data.size.zero?
+
+        shapes = prepare_data.map do |name, field_types|
+          { 'name' => name, 'fieldTypes' => field_types }
+        end
+
+        { 'contextShapes' => { 'shapes' => shapes } }
+      end
+
+      private
+
+      def each_named_context(context)
+        if context.respond_to?(:contexts)
+          # Quonfig::Context — each_pair yields (name, NamedContext)
+          context.contexts.each_pair do |name, named|
+            yield name, (named.respond_to?(:to_h) ? named.to_h : named)
+          end
+        elsif context.is_a?(Hash)
+          context.each_pair do |name, values|
+            values = { name.to_s => values } unless values.is_a?(Hash)
+            yield name, values
+          end
+        end
+      end
+    end
+  end
+end

data/lib/quonfig/telemetry/evaluation_summaries_aggregator.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Quonfig
+  module Telemetry
+    # Accumulates per-evaluation counts grouped by (config_key, config_type),
+    # with one counter per unique (config_id, conditional_value_index,
+    # weighted_value_index, selected_value). Emits api-telemetry's
+    # `summaries` event — JSON wire format matching sdk-node and sdk-go.
+    #
+    # Ported from ReforgeHQ/sdk-ruby evaluation_summary_aggregator.rb and
+    # adapted to the JSON wire format (EvaluationSummariesSchema in
+    # api-telemetry/src/telemetry-schemas.ts).
+    class EvaluationSummariesAggregator
+      attr_reader :data
+
+      def initialize(max_keys:)
+        @max_keys = max_keys
+        @data = Concurrent::Hash.new
+        @start_at_ms = nil
+        @mutex = Mutex.new
+      end
+
+      # Record a single evaluation.
+      #
+      # @param config_id [String]
+      # @param config_key [String]
+      # @param config_type [String, nil] "config", "feature_flag", etc.
+      #   "log_level" evaluations are intentionally dropped (they're high
+      #   volume and not useful for usage analytics).
+      # @param conditional_value_index [Integer] rule index
+      # @param weighted_value_index [Integer, nil]
+      # @param selected_value [Object] the unwrapped evaluated value
+      # @param reason [Integer] wire reason code (see Quonfig::Reason::WIRE_*)
+      def record(config_id:, config_key:, config_type:,
+                 conditional_value_index:, weighted_value_index: nil,
+                 selected_value: nil, reason: 0)
+        return if @max_keys <= 0
+        return if config_type == 'log_level'
+
+        group_key = [config_key, config_type]
+        counter_key = [config_id, conditional_value_index, weighted_value_index, selected_value]
+
+        @mutex.synchronize do
+          unless @data.key?(group_key)
+            return if @data.size >= @max_keys
+
+            @data[group_key] = {}
+          end
+          @start_at_ms ||= Quonfig::TimeHelpers.now_in_ms
+
+          bucket = @data[group_key]
+          bucket[counter_key] ||= { count: 0, reason: reason }
+          bucket[counter_key][:count] += 1
+        end
+      end
+
+      # Drain accumulated summaries into a single telemetry event payload.
+      # Returns +nil+ when there is nothing to ship.
+      def drain_event
+        snapshot = nil
+        start_at = nil
+
+        @mutex.synchronize do
+          return nil if @data.empty?
+
+          snapshot = @data
+          start_at = @start_at_ms
+          @data = Concurrent::Hash.new
+          @start_at_ms = nil
+        end
+
+        summaries = snapshot.map do |(config_key, config_type), counters|
+          counter_list = counters.map do |(config_id, cvi, wvi, sval), meta|
+            counter = {
+              'configId' => config_id,
+              'conditionalValueIndex' => cvi,
+              'configRowIndex' => 0,
+              'selectedValue' => wrap_selected_value(sval),
+              'count' => meta[:count],
+              'reason' => meta[:reason]
+            }
+            counter['weightedValueIndex'] = wvi unless wvi.nil?
+            counter
+          end
+
+          entry = { 'key' => config_key, 'counters' => counter_list }
+          entry['type'] = config_type unless config_type.nil?
+          entry
+        end
+
+        {
+          'summaries' => {
+            'start' => start_at || Quonfig::TimeHelpers.now_in_ms,
+            'end' => Quonfig::TimeHelpers.now_in_ms,
+            'summaries' => summaries
+          }
+        }
+      end
+
+      private
+
+      # Wrap the evaluated value in the Prefab-proto-style tagged hash that
+      # api-telemetry ClickHouse ingestion expects. Keys match sdk-go's
+      # marshalSelectedValue (proto field names): bool / int / double /
+      # string / stringList.
+      def wrap_selected_value(value)
+        case value
+        when true, false then { 'bool' => value }
+        when Integer     then { 'int' => value }
+        when Float       then { 'double' => value }
+        when String      then { 'string' => value }
+        when Array       then { 'stringList' => value.map(&:to_s) }
+        when nil         then { 'string' => '' }
+        else                  { 'string' => value.to_s }
+        end
+      end
+    end
+  end
+end

data/lib/quonfig/telemetry/example_contexts_aggregator.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Quonfig
+  module Telemetry
+    # Samples *example* contexts seen during evaluation. Dedupes by the
+    # concatenation of each named context's "key" property and rate-limits
+    # each grouped key to once per hour.
+    #
+    # Emits api-telemetry's `exampleContexts` event — JSON wire format,
+    # matching sdk-node and sdk-go. This is NOT the old Prefab protobuf.
+    class ExampleContextsAggregator
+      ONE_HOUR_SECONDS = 60 * 60
+
+      attr_reader :data, :cache
+
+      def initialize(max_contexts:, rate_limit_seconds: ONE_HOUR_SECONDS)
+        @max_contexts = max_contexts
+        @data = Concurrent::Array.new
+        @cache = Quonfig::RateLimitCache.new(rate_limit_seconds)
+      end
+
+      # Record a context for possible emission. Expects a Quonfig::Context.
+      # Contexts with no grouped_key (nothing to dedupe on) are dropped to
+      # avoid shipping empty/anonymous samples.
+      def record(context)
+        return if @max_contexts <= 0
+        return if context.nil?
+
+        key = grouped_key_for(context)
+        return if key.nil? || key.empty?
+
+        return unless @data.size < @max_contexts && !@cache.fresh?(key)
+
+        @cache.set(key)
+        @data.push([Quonfig::TimeHelpers.now_in_ms, context])
+      end
+
+      def prepare_data
+        to_ship = @data.dup
+        @data.clear
+        @cache.prune
+        to_ship
+      end
+
+      # Drain accumulated examples into a single telemetry event payload
+      # matching api-telemetry's ExampleContextsSchema, or +nil+ if empty.
+      def drain_event
+        return nil if @data.size.zero?
+
+        to_ship = prepare_data
+
+        examples = to_ship.map do |timestamp_ms, context|
+          contexts_list = contexts_to_list(context)
+          { 'timestamp' => timestamp_ms, 'contextSet' => { 'contexts' => contexts_list } }
+        end
+
+        { 'exampleContexts' => { 'examples' => examples } }
+      end
+
+      private
+
+      def grouped_key_for(context)
+        return context.grouped_key if context.respond_to?(:grouped_key)
+
+        # Fallback for plain-Hash contexts: concatenate each named context's
+        # "key" (or "trackingId") value.
+        return nil unless context.is_a?(Hash)
+
+        context.values.map do |ctx|
+          next nil unless ctx.is_a?(Hash)
+
+          ctx['key'] || ctx[:key] || ctx['trackingId'] || ctx[:trackingId]
+        end.compact.map(&:to_s).reject(&:empty?).sort.join('|')
+      end
+
+      def contexts_to_list(context)
+        if context.respond_to?(:contexts)
+          context.contexts.map do |name, named|
+            values = named.respond_to?(:to_h) ? named.to_h : named
+            { 'type' => name.to_s, 'values' => stringify_values(values) }
+          end
+        elsif context.is_a?(Hash)
+          context.map do |name, values|
+            values = { name.to_s => values } unless values.is_a?(Hash)
+            { 'type' => name.to_s, 'values' => stringify_values(values) }
+          end
+        else
+          []
+        end
+      end
+
+      def stringify_values(hash)
+        return {} unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) do |(k, v), acc|
+          acc[k.to_s] = v
+        end
+      end
+    end
+  end
+end