quonfig 0.0.5 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb6a88a2132fd0fe54fc656ffe1b81916e4487258c2a54dd5589d0bb56b1e300
-  data.tar.gz: e91e3cce0cc73793e2c0c1fb407192cbd5a8caad9c96bfbfae6d6bf2fa69ea78
+  metadata.gz: 18707780a8ad33c299973f4de01bc0b76d10161902f977b9771c10c2d4a23fde
+  data.tar.gz: 6980b904632659b97f16636e9a317bc8b3e8cbf02cc0b8f75ecf51325b8ba472
 SHA512:
-  metadata.gz: d33195dcf4fd9b52f8e245e102fbf21a405626aaa8e1157294a79c83cb8a1f91b78249782a9b7318728f31d342adc9f4565d082886d041d53a44995f8adfcb45
-  data.tar.gz: fa6b7dd2497f9d202e985619ccccf754162b538c1cd7ffc41d0c7f6679e83d55ac1739d3ed1dc76931b7a9a14be1db9e5f35514a9ff86c9997feecda9342159d
+  metadata.gz: 74c6a59b81fd222ddd522e52301ea74a1f9bc76b18ecbfe50c01a46e21539bdc5cea6a38a927938fb497f6003a64a2e796d177f2ed3ee527d5891f6cd9ca63a4
+  data.tar.gz: 94b1c109e6db3df2ea115e62f80f099430752779faa9655ee6f53c20c614fa42ccdc8e350342985cb09861e286bd91b857381508849a81fada865927c98f7f22

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 0.0.8 - 2026-04-26
+
+- **Fix (gemspec): drop deleted `scripts/` entry from manifest** — regenerated
+  juwelier gemspec so `gem build` no longer fails on the missing
+  `scripts/generate_integration_tests.rb` file. Also untracked stray
+  `.DS_Store`. v0.0.7 was tagged but never published due to this bug.
+
+## 0.0.7 - 2026-04-26
+
+- **New: `client.enabled?` / `client.default` / `client.client_construction` integration helpers** —
+  Adds aggregator helpers used by the cross-SDK post + telemetry integration suites.
+- **New: telemetry eval-summaries aggregator + `at_exit` drain (qfg-9x7)** —
+  Periodically batches evaluation summaries and drains them on process exit so
+  short-lived scripts still report telemetry.
+- **New: context telemetry aggregators ported from sdk-node** — context shapes
+  and example-contexts ship through the same aggregator path as sdk-node and
+  sdk-go.
+- **New errors: `DecryptionError`, `MissingEnvironmentError`,
+  `InvalidEnvironmentError`** — explicit error classes raised from the resolver
+  and datadir loaders.
+- **Resolver: provided ENV_VAR resolution + coercion (qfg-08q)** — config values
+  marked `provided` now resolve from the environment at evaluation time and are
+  coerced to the declared value type.
+- **Fix (resolver): raise on missing key, decode weighted/duration/decryption** —
+  `get_or_raise` now raises `MissingDefaultError` for unknown keys, and weighted /
+  duration / decryption value types decode correctly through the JSON resolver.
+- **Fix (context): `grouped_key` drops anonymous contexts** — anonymous contexts
+  are no longer mixed into the grouped-context key, matching sdk-node and sdk-go.
+
+## 0.0.6 - 2026-04-22
+
+- **New: `Quonfig::StdlibFormatter` + `client.stdlib_formatter(logger_name:)`** —
+  Ruby's built-in `::Logger` now gets drop-in dynamic log-level gating,
+  on par with the existing SemanticLogger integration. The client helper
+  returns a Proc matching the stdlib `logger.formatter =` contract
+  (`(severity, datetime, progname, msg) -> String`). For each log call
+  the proc evaluates `should_log?(logger_path: logger_name || progname,
+  desired_level: severity)` and either formats the record or returns an
+  empty string (which `::Logger` writes as zero bytes, suppressing the
+  line). `logger_name` flows into `quonfig-sdk-logging.key` verbatim —
+  no normalization — so customer rules target exact class names.
+  Raises `Quonfig::Error` if `logger_key` was not set at init. Parallels
+  sdk-node's Winston formatter, sdk-python's `logging.Filter`, and
+  sdk-go's `slog.Handler`. Closes Stage 2 of the per-SDK logger-path
+  rollout.
+
 ## 0.0.5 - 2026-04-22
 
 - **BREAKING — SemanticLoggerFilter context key renamed.** The filter

data/README.md

@@ -203,6 +203,42 @@ Pass `key_prefix:` to use a prefix other than `log-levels.`:
 client.semantic_logger_filter(key_prefix: 'debug.')
 ```
 
+## Dynamic log levels with stdlib Logger
+
+If you use Ruby's built-in `::Logger` instead of SemanticLogger, wire the
+formatter returned by `client.stdlib_formatter` into your logger:
+
+```ruby
+require 'quonfig'
+require 'logger'
+
+client = Quonfig::Client.new(
+  sdk_key:    ENV['QUONFIG_BACKEND_SDK_KEY'],
+  logger_key: 'log-level.my-app'
+)
+
+logger = ::Logger.new($stdout)
+logger.level = ::Logger::DEBUG
+logger.formatter = client.stdlib_formatter(logger_name: 'MyApp::Services::Auth')
+```
+
+The formatter asks the client `should_log?(logger_path:, desired_level:)`
+for every call; lines below the configured level return an empty string
+(which `::Logger` writes as zero bytes, suppressing the line). `logger_name`
+is passed to Quonfig verbatim under `quonfig-sdk-logging.key` so a single
+`log-level.my-app` config can drive per-class overrides via rules like
+`PROP_STARTS_WITH_ONE_OF "MyApp::Services::"`.
+
+Omit `logger_name:` to have the formatter fall through to the Logger's
+`progname` at call time:
+
+```ruby
+logger.formatter = client.stdlib_formatter
+logger.progname  = 'MyApp::Services::Auth'
+```
+
+If both are supplied, the explicit `logger_name:` wins.
+
 ## Documentation
 
 Full documentation, including SPEC, SDK reference, and operational guides, is

data/VERSION

@@ -1 +1 @@
-0.0.5
+0.0.8

data/lib/quonfig/client.rb

@@ -21,7 +21,7 @@ module Quonfig
     LOG = Quonfig::InternalLogger.new(self)
 
     attr_reader :options, :resolver, :store, :evaluator, :instance_hash,
-                :config_loader
+                :config_loader, :telemetry_reporter
 
     def initialize(options = nil, store: nil, **option_kwargs)
       @options =
@@ -41,6 +41,7 @@ module Quonfig
       @sse_client = nil
       @poll_thread = nil
       @stopped = false
+      @telemetry_reporter = nil
 
       # If the caller injected a store, we're in test/bootstrap mode; skip I/O.
       return if store
@@ -50,15 +51,27 @@ module Quonfig
       else
         initialize_network_mode
       end
+
+      initialize_telemetry
     end
 
     # ---- Lookup --------------------------------------------------------
 
     def get(key, default = NO_DEFAULT_PROVIDED, jit_context = NO_DEFAULT_PROVIDED)
       ctx = build_context(jit_context)
-      result = @resolver.get(key, ctx)
+      record_context_for_telemetry(ctx)
+      result =
+        begin
+          @resolver.get(key, ctx)
+        rescue Quonfig::Errors::MissingDefaultError
+          # The Resolver raises (matching Quonfig.get_or_raise semantics).
+          # The Client's get applies the caller-provided default *or* the
+          # configured on_no_default policy via handle_missing.
+          nil
+        end
       return handle_missing(key, default) if result.nil?
 
+      record_evaluation_for_telemetry(result)
       result.unwrapped_value
     end
 
@@ -125,6 +138,29 @@ module Quonfig
         Quonfig::SemanticLoggerFilter.new(self, config_key: config_key)
     end
 
+    # Build a formatter Proc for Ruby's built-in +::Logger+. The returned
+    # proc honors dynamic log levels from the client's +logger_key+ config:
+    # for each log call, it evaluates +should_log?+ and either formats the
+    # record or returns an empty string (suppressing output).
+    #
+    # Matches ReforgeHQ's +stdlib_formatter+ API name (snake_case).
+    #
+    # Usage:
+    #   logger = ::Logger.new($stdout)
+    #   logger.formatter = client.stdlib_formatter                       # uses progname
+    #   logger.formatter = client.stdlib_formatter(logger_name: 'MyApp') # fixed name
+    #
+    # Raises +Quonfig::Error+ if +logger_key+ was not set at init — parallels
+    # +should_log?+'s behavior.
+    #
+    # @param logger_name [String, nil] fallback logger identifier used when
+    #   +progname+ isn't supplied by the Logger call site. If both are
+    #   present, +logger_name+ wins.
+    # @return [Proc] a +(severity, datetime, progname, msg) -> String+ proc.
+    def stdlib_formatter(logger_name: nil)
+      Quonfig::StdlibFormatter.build(self, logger_name: logger_name)
+    end
+
     # The configured +logger_key+ from Options — the Quonfig config key the
     # higher-level +should_log?+ helper evaluates per-logger. +nil+ if the
     # client was not configured for dynamic log levels.
@@ -200,6 +236,13 @@ module Quonfig
       thread = @poll_thread
       @poll_thread = nil
       thread&.kill
+
+      begin
+        @telemetry_reporter&.stop
+      rescue StandardError => e
+        LOG.debug "Error stopping telemetry reporter: #{e.message}"
+      end
+      @telemetry_reporter = nil
     end
 
     def fork
@@ -212,6 +255,93 @@ module Quonfig
 
     private
 
+    # Construct and start the telemetry reporter if the options permit it.
+    # The reporter runs on a background thread and periodically POSTs
+    # context-shape and example-context batches to +telemetry_destination+.
+    def initialize_telemetry
+      shape_aggregator = nil
+      example_aggregator = nil
+      summaries_aggregator = nil
+
+      if @options.collect_max_shapes.to_i > 0
+        shape_aggregator = Quonfig::Telemetry::ContextShapeAggregator.new(
+          max_shapes: @options.collect_max_shapes
+        )
+      end
+
+      if @options.collect_max_example_contexts.to_i > 0
+        example_aggregator = Quonfig::Telemetry::ExampleContextsAggregator.new(
+          max_contexts: @options.collect_max_example_contexts
+        )
+      end
+
+      if @options.collect_max_evaluation_summaries.to_i > 0
+        summaries_aggregator = Quonfig::Telemetry::EvaluationSummariesAggregator.new(
+          max_keys: @options.collect_max_evaluation_summaries
+        )
+      end
+
+      return if shape_aggregator.nil? && example_aggregator.nil? && summaries_aggregator.nil?
+
+      @telemetry_reporter = Quonfig::Telemetry::TelemetryReporter.new(
+        options: @options,
+        instance_hash: @instance_hash,
+        context_shape_aggregator: shape_aggregator,
+        example_contexts_aggregator: example_aggregator,
+        evaluation_summaries_aggregator: summaries_aggregator,
+        sync_interval: @options.collect_sync_interval
+      )
+
+      return unless @telemetry_reporter.enabled?
+
+      @telemetry_reporter.start
+    rescue StandardError => e
+      LOG.warn "[quonfig] Telemetry init failed: #{e.class}: #{e.message}"
+      @telemetry_reporter = nil
+    end
+
+    # Feed a matched EvalResult into the evaluation_summaries aggregator.
+    # A no-op when telemetry is disabled or eval-summaries collection is off.
+    def record_evaluation_for_telemetry(result)
+      return if @telemetry_reporter.nil?
+      return if result.nil?
+
+      config = result.config
+      return if config.nil?
+
+      @telemetry_reporter.record_evaluation(
+        config_id: config_field(config, :id),
+        config_key: config_field(config, :key),
+        config_type: config_field(config, :type),
+        conditional_value_index: result.rule_index,
+        weighted_value_index: nil,
+        selected_value: result.unwrapped_value,
+        reason: result.wire_reason
+      )
+    rescue StandardError => e
+      LOG.debug "[quonfig] Telemetry record_evaluation error: #{e.class}: #{e.message}"
+    end
+
+    def config_field(config, key)
+      return nil if config.nil?
+
+      config[key.to_s] || config[key.to_sym]
+    end
+
+    # Feed every evaluated context into the telemetry aggregators. A no-op
+    # when telemetry is disabled or no aggregators are active.
+    def record_context_for_telemetry(context)
+      return if @telemetry_reporter.nil?
+      return if context.nil?
+
+      context_obj = context.is_a?(Quonfig::Context) ? context : Quonfig::Context.new(context)
+      return if context_obj.blank?
+
+      @telemetry_reporter.record(context_obj)
+    rescue StandardError => e
+      LOG.debug "[quonfig] Telemetry record error: #{e.class}: #{e.message}"
+    end
+
     def load_datadir_into_store
       envelope = Quonfig::Datadir.load_envelope(@options.datadir, @options.environment)
       envelope.configs.each { |cfg| @store.set(cfg['key'], cfg) }

data/lib/quonfig/context.rb

@@ -85,8 +85,17 @@ module Quonfig
       @contexts[name.to_s] || NamedContext.new(name, {})
     end
 
+    # Concatenate each named context's `key` (or `trackingId`) value into
+    # a stable identifier used for example-contexts dedupe. Mirrors
+    # sdk-node's groupedKey: contexts that don't have a `key` property
+    # contribute nothing — the resulting string is empty for "anonymous"
+    # contexts so the example aggregator can drop them entirely.
     def grouped_key
-      @contexts.map { |_, ctx| ctx.key }.sort.join('|')
+      @contexts.values.map do |ctx|
+        h = ctx.to_h
+        v = h['key'] || h[:key] || h['trackingId'] || h[:trackingId]
+        v.nil? ? nil : v.to_s
+      end.compact.reject(&:empty?).sort.join('|')
     end
 
     include Comparable

data/lib/quonfig/datadir.rb

@@ -59,8 +59,7 @@ module Quonfig
       environment ||= ENV['QUONFIG_ENVIRONMENT']
 
       if environment.nil? || environment.empty?
-        raise ArgumentError,
-              '[quonfig] Environment required for datadir mode; set the `environment` option or QUONFIG_ENVIRONMENT env var'
+        raise Quonfig::Errors::MissingEnvironmentError
       end
 
       unless File.exist?(quonfig_path)
@@ -70,8 +69,7 @@ module Quonfig
       environments = JSON.parse(File.read(quonfig_path)).fetch('environments', [])
 
       if !environments.empty? && !environments.include?(environment)
-        raise ArgumentError,
-              "[quonfig] Environment \"#{environment}\" not found in workspace; available environments: #{environments.join(', ')}"
+        raise Quonfig::Errors::InvalidEnvironmentError.new(environment, environments)
       end
 
       environment

data/lib/quonfig/errors/decryption_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Quonfig
+  module Errors
+    # Raised when a confidential config's ciphertext cannot be decrypted —
+    # either the configured `decryptWith` key is missing/empty, or the
+    # AES-GCM payload itself is malformed/tampered.
+    #
+    # Mirrors sdk-python's QuonfigDecryptionError. Sdk-node currently
+    # raises plain `Error` for the same path; this class is the Ruby
+    # equivalent of the dedicated exception type.
+    class DecryptionError < Quonfig::Error
+      def initialize(key, cause = nil)
+        message = "Decryption failed for config '#{key}'"
+        message += ": #{cause}" if cause && !cause.to_s.empty?
+        super(message)
+      end
+    end
+  end
+end

data/lib/quonfig/errors/env_var_parse_error.rb

@@ -4,7 +4,14 @@ module Quonfig
   module Errors
     class EnvVarParseError < Quonfig::Error
       def initialize(env_var, config, env_var_name)
-        super("Evaluating #{config.key} couldn't coerce #{env_var_name} of #{env_var} to #{config.value_type}")
+        key, value_type =
+          if config.is_a?(Hash)
+            [config[:key] || config['key'],
+             config[:value_type] || config['value_type'] || config['valueType']]
+          else
+            [config.key, config.value_type]
+          end
+        super("Evaluating #{key} couldn't coerce #{env_var_name} of #{env_var} to #{value_type}")
       end
     end
   end

data/lib/quonfig/errors/invalid_environment_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Quonfig
+  module Errors
+    # Raised when the requested environment (via `environment:` option or
+    # QUONFIG_ENVIRONMENT) isn't listed in the workspace's `quonfig.json`.
+    # Catches typos like `"prdoduction"` early instead of silently
+    # evaluating against default rules.
+    class InvalidEnvironmentError < Quonfig::Error
+      def initialize(environment, available = nil)
+        message = "[quonfig] Environment \"#{environment}\" not found in workspace"
+        if available && !Array(available).empty?
+          message += "; available environments: #{Array(available).join(', ')}"
+        end
+        super(message)
+      end
+    end
+  end
+end

data/lib/quonfig/errors/missing_environment_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Quonfig
+  module Errors
+    # Raised when datadir mode is engaged but no environment was supplied
+    # (neither the `environment:` option nor the QUONFIG_ENVIRONMENT env
+    # var is set). Datadir mode requires an explicit environment; without
+    # one the loader cannot pick the right environment row from each
+    # config's `environments` array.
+    class MissingEnvironmentError < Quonfig::Error
+      def initialize(message = nil)
+        message ||= '[quonfig] Environment required for datadir mode; ' \
+                    'set the `environment` option or QUONFIG_ENVIRONMENT env var'
+        super(message)
+      end
+    end
+  end
+end

data/lib/quonfig/evaluator.rb

@@ -409,14 +409,54 @@ module Quonfig
   # raw JSON Value hash (#value) and a coerced Ruby value (#unwrapped_value).
   # The test suite and integration helpers consume both shapes.
   class EvalResult
+    # Integer reason codes for the api-telemetry EvalSummaries wire
+    # format. Match sdk-node/src/reason.ts.
+    REASON_UNKNOWN          = 0
+    REASON_STATIC           = 1
+    REASON_TARGETING_MATCH  = 2
+    REASON_SPLIT            = 3
+
     attr_reader :value, :rule_index, :config
+    attr_accessor :weighted_value_index
 
-    def initialize(value:, rule_index:, config:)
+    def initialize(value:, rule_index:, config:, weighted_value_index: nil)
       @value = value
       @rule_index = rule_index
       @config = config
+      @weighted_value_index = weighted_value_index
     end
 
+    # Integer reason code for telemetry. Mirrors sdk-node's computeReason:
+    # SPLIT when a weighted variant is picked, STATIC when the first rule
+    # of a config with no targeting rules matched, otherwise TARGETING_MATCH.
+    def wire_reason
+      return REASON_SPLIT unless @weighted_value_index.nil?
+      return REASON_STATIC if @rule_index == 0 && !EvalResult.send(:targeting_rules?, @config)
+
+      REASON_TARGETING_MATCH
+    end
+
+    # True if any rule on the config (default or environment) has a
+    # non-ALWAYS_TRUE criterion. Used to decide STATIC vs TARGETING_MATCH.
+    def self.targeting_rules?(config)
+      return false if config.nil?
+
+      rules = []
+      %i[default environment].each do |section_key|
+        section = config[section_key.to_s] || config[section_key]
+        next if section.nil?
+
+        section_rules = section['rules'] || section[:rules] || []
+        rules.concat(section_rules)
+      end
+
+      rules.any? do |rule|
+        criteria = rule['criteria'] || rule[:criteria] || []
+        criteria.any? { |c| (c['operator'] || c[:operator]) != 'ALWAYS_TRUE' }
+      end
+    end
+    private_class_method :targeting_rules?
+
     # Raw underlying value without type coercion.
     def raw_value
       return nil if @value.nil?
@@ -446,7 +486,7 @@ module Quonfig
       when 'string'      then raw.to_s
       when 'string_list' then raw.is_a?(Array) ? raw.map(&:to_s) : []
       when 'log_level'   then raw.is_a?(Numeric) ? raw : raw.to_s
-      when 'duration'    then raw.to_s
+      when 'duration'    then duration_to_millis(raw)
       when 'json'
         # JSON values must be native JS/Ruby types on the wire.
         raw
@@ -460,5 +500,27 @@ module Quonfig
     def value_type
       type
     end
+
+    private
+
+    # Coerce an ISO 8601 duration value (e.g. "PT0.2S", "P1DT6H2M1.5S")
+    # to integer milliseconds. The wire format may either be a bare ISO
+    # string in `value` or the structured `{ seconds, nanos }` proto-style
+    # shape. Mirrors sdk-node Resolver#unwrapValue duration branch.
+    def duration_to_millis(raw)
+      case raw
+      when Numeric
+        raw.to_i
+      when String
+        seconds = Quonfig::Duration.parse(raw)
+        (seconds * 1000).round
+      when Hash
+        secs = (raw['seconds'] || raw[:seconds] || 0).to_f
+        nanos = (raw['nanos']   || raw[:nanos]   || 0).to_f
+        (secs * 1000 + nanos / 1_000_000.0).round
+      else
+        raw
+      end
+    end
   end
 end

data/lib/quonfig/http_connection.rb

@@ -5,7 +5,7 @@ require 'json'
 
 module Quonfig
   class HttpConnection
-    SDK_VERSION = 'ruby-0.1.0'
+    SDK_VERSION = "ruby-#{Quonfig::VERSION}".freeze
 
     JSON_HEADERS = {
       'Content-Type' => 'application/json',