quonfig 0.0.6 → 0.0.8

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

data/lib/quonfig/telemetry/telemetry_reporter.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Quonfig
+  module Telemetry
+    # Owns the background thread that periodically drains the context
+    # aggregators and POSTs a JSON telemetry batch to
+    # +<telemetry_destination>/api/v1/telemetry/+.
+    #
+    # Wire shape matches api-telemetry's TelemetryEventsSchema:
+    #
+    #   {
+    #     "instanceHash": "...",
+    #     "events": [
+    #       { "summaries":       { "start": ..., "end": ..., "summaries": [...] } },
+    #       { "contextShapes":   { "shapes":   [...] } },
+    #       { "exampleContexts": { "examples": [...] } }
+    #     ]
+    #   }
+    #
+    # Auth is HTTP Basic with username "1" and the SDK key as password
+    # (matching sdk-node and sdk-go). The +X-Quonfig-SDK-Version+ header
+    # carries the +ruby-<VERSION>+ identifier.
+    class TelemetryReporter
+      LOG = Quonfig::InternalLogger.new(self)
+
+      DEFAULT_INITIAL_DELAY_SECONDS = 8
+      DEFAULT_MAX_DELAY_SECONDS = 600
+
+      def initialize(options:, instance_hash:,
+                     context_shape_aggregator: nil,
+                     example_contexts_aggregator: nil,
+                     evaluation_summaries_aggregator: nil,
+                     sync_interval: nil,
+                     http_connection: nil)
+        @options = options
+        @instance_hash = instance_hash
+        @sdk_key = options.sdk_key
+        @telemetry_destination = options.telemetry_destination
+        @context_shape_aggregator = context_shape_aggregator
+        @example_contexts_aggregator = example_contexts_aggregator
+        @evaluation_summaries_aggregator = evaluation_summaries_aggregator
+        @http_connection = http_connection
+        @sync_interval = calculate_sync_interval(sync_interval)
+        @stopped = Concurrent::AtomicBoolean.new(false)
+        @thread = nil
+        @at_exit_registered = false
+      end
+
+      def enabled?
+        return false if @sdk_key.nil? || @sdk_key.to_s.empty?
+        return false if @telemetry_destination.nil? || @telemetry_destination.to_s.empty?
+
+        !@context_shape_aggregator.nil? ||
+          !@example_contexts_aggregator.nil? ||
+          !@evaluation_summaries_aggregator.nil?
+      end
+
+      # Record a context across the context-driven aggregators. Evaluation
+      # summaries are recorded separately via
+      # +record_evaluation(...)+ since they require the evaluation result.
+      def record(context)
+        return if context.nil?
+
+        @context_shape_aggregator&.push(context)
+        @example_contexts_aggregator&.record(context)
+      end
+
+      def record_evaluation(**kwargs)
+        @evaluation_summaries_aggregator&.record(**kwargs)
+      end
+
+      def start
+        return if @thread&.alive?
+        return unless enabled?
+
+        @stopped.make_false
+        register_at_exit_handler
+        @thread = Thread.new do
+          Thread.current.name = 'quonfig-telemetry-reporter'
+          LOG.debug "Telemetry reporter started instance_hash=#{@instance_hash} destination=#{@telemetry_destination}"
+
+          until @stopped.true?
+            begin
+              sleep_duration = @sync_interval.call
+              slept = 0.0
+              step = 0.5
+              while slept < sleep_duration && !@stopped.true?
+                sleep([step, sleep_duration - slept].min)
+                slept += step
+              end
+              break if @stopped.true?
+
+              sync
+            rescue StandardError => e
+              LOG.warn "[quonfig] Telemetry reporter error: #{e.class}: #{e.message}"
+            end
+          end
+        end
+      end
+
+      def stop
+        @stopped.make_true
+        thread = @thread
+        @thread = nil
+        thread&.wakeup if thread&.alive?
+        # Final drain attempt on stop so tests / short-lived processes
+        # don't silently drop pending telemetry.
+        begin
+          sync
+        rescue StandardError => e
+          LOG.debug "[quonfig] Final telemetry sync failed: #{e.class}: #{e.message}"
+        end
+      end
+
+      # Drain all aggregators and POST the batch. Public so tests can
+      # trigger a sync without waiting for the background loop.
+      def sync
+        events = []
+        if (summaries_event = @evaluation_summaries_aggregator&.drain_event)
+          events << summaries_event
+        end
+        if (shape_event = @context_shape_aggregator&.drain_event)
+          events << shape_event
+        end
+        if (example_event = @example_contexts_aggregator&.drain_event)
+          events << example_event
+        end
+
+        return if events.empty?
+
+        payload = {
+          'instanceHash' => @instance_hash,
+          'events' => events
+        }
+
+        post(payload)
+      end
+
+      # Visible for tests.
+      def at_exit_registered?
+        @at_exit_registered
+      end
+
+      private
+
+      # Rails / Passenger / Puma workers often terminate via SIGTERM without
+      # a chance to call Client#stop. Register a Kernel.at_exit hook on
+      # first start so the in-flight batch still gets flushed.
+      def register_at_exit_handler
+        return if @at_exit_registered
+
+        Kernel.at_exit { final_drain_on_exit }
+        @at_exit_registered = true
+      end
+
+      # Idempotent final drain. Safe to call after #stop has already
+      # drained: aggregators return nil when empty and #sync becomes a
+      # no-op.
+      def final_drain_on_exit
+        @stopped.make_true
+        sync
+      rescue StandardError => e
+        LOG.debug "[quonfig] at_exit telemetry drain failed: #{e.class}: #{e.message}"
+      end
+
+      def post(payload)
+        conn = http_connection
+        return if conn.nil?
+
+        response = conn.post('/api/v1/telemetry/', payload)
+        status = response.respond_to?(:status) ? response.status : nil
+        if status && status >= 400
+          LOG.warn "[quonfig] Telemetry POST failed: #{status}"
+        else
+          LOG.debug "[quonfig] Telemetry POST ok: events=#{payload['events'].size}"
+        end
+        response
+      end
+
+      def http_connection
+        @http_connection ||= begin
+          return nil if @sdk_key.nil? || @telemetry_destination.nil?
+
+          Quonfig::HttpConnection.new(@telemetry_destination, @sdk_key)
+        end
+      end
+
+      def calculate_sync_interval(sync_interval)
+        return proc { sync_interval } if sync_interval.is_a?(Numeric)
+        return sync_interval if sync_interval.respond_to?(:call)
+
+        Quonfig::ExponentialBackoff.new(
+          initial_delay: DEFAULT_INITIAL_DELAY_SECONDS,
+          max_delay: DEFAULT_MAX_DELAY_SECONDS,
+          multiplier: 1.5
+        )
+      end
+    end
+  end
+end

data/lib/quonfig.rb

@@ -35,6 +35,9 @@ 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/errors/decryption_error'
+require 'quonfig/errors/missing_environment_error'
+require 'quonfig/errors/invalid_environment_error'
 require 'quonfig/options'
 require 'quonfig/rate_limit_cache'
 require 'quonfig/weighted_value_resolver'
@@ -48,6 +51,11 @@ require 'quonfig/sse_config_client'
 require 'quonfig/http_connection'
 require 'quonfig/caching_http_connection'
 require 'quonfig/context'
+require 'quonfig/telemetry/context_shape'
+require 'quonfig/telemetry/context_shape_aggregator'
+require 'quonfig/telemetry/example_contexts_aggregator'
+require 'quonfig/telemetry/evaluation_summaries_aggregator'
+require 'quonfig/telemetry/telemetry_reporter'
 require 'quonfig/client'
 require 'quonfig/bound_client'
 require 'quonfig/semantic_logger_filter'