quonfig 0.0.6 → 0.0.8

data/test/test_stdlib_formatter.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+require 'logger'
+require 'stringio'
+
+# Verifies Quonfig::StdlibFormatter — an adapter that plugs Quonfig's dynamic
+# log-level evaluation into Ruby's built-in ::Logger via the
+# `logger.formatter = <proc>` contract. The formatter is a callable with
+# signature (severity, datetime, progname, msg) -> String. Returning an empty
+# string suppresses the log line (Logger writes exactly what the formatter
+# returns).
+#
+# The Ruby stdlib severity strings ("DEBUG", "INFO", "WARN", "ERROR", "FATAL",
+# "ANY") are mapped to the quonfig level symbols used by the evaluator
+# (:debug, :info, :warn, :error, :fatal). progname flows into the evaluator
+# under `quonfig-sdk-logging.key` verbatim, no normalization — matching the
+# SemanticLoggerFilter.
+class TestStdlibFormatter < Minitest::Test
+  LOG_LEVEL_KEY = 'log-level.my-app'
+
+  # Build a minimal config fixture: a string config whose single rule always
+  # resolves to `level`. Mirrors the shape used in test_should_log.rb so we
+  # exercise the full get()/resolver/evaluator path rather than stubbing.
+  def make_log_level_config(key:, level:)
+    {
+      'id' => '1',
+      'key' => key,
+      'type' => 'config',
+      'valueType' => 'string',
+      'sendToClientSdk' => false,
+      'default' => {
+        'rules' => [
+          { 'criteria' => [{ 'operator' => 'ALWAYS_TRUE' }],
+            'value' => { 'type' => 'string', 'value' => level } }
+        ]
+      },
+      'environment' => nil
+    }
+  end
+
+  def store_with(*configs)
+    store = Quonfig::ConfigStore.new
+    configs.each { |c| store.set(c['key'], c) }
+    store
+  end
+
+  def client_with(store, **options)
+    Quonfig::Client.new(Quonfig::Options.new(**options), store: store)
+  end
+
+  # ---- error behavior --------------------------------------------------
+
+  def test_stdlib_formatter_raises_without_logger_key
+    client = client_with(Quonfig::ConfigStore.new)
+    err = assert_raises(Quonfig::Error) { client.stdlib_formatter }
+    assert_match(/logger_key/, err.message)
+  end
+
+  # ---- proc contract ---------------------------------------------------
+
+  def test_stdlib_formatter_returns_a_callable_with_4_arity
+    store = store_with(make_log_level_config(key: LOG_LEVEL_KEY, level: 'info'))
+    client = client_with(store, logger_key: LOG_LEVEL_KEY)
+
+    formatter = client.stdlib_formatter
+    assert_respond_to formatter, :call
+    # Ruby Logger invokes formatter with exactly 4 args; a Proc takes any arity,
+    # but arity should be 4 so it matches the Logger contract faithfully.
+    assert_equal 4, formatter.arity
+  end
+
+  # ---- gating ----------------------------------------------------------
+
+  def test_formatter_drops_below_configured_level_returning_empty_string
+    store = store_with(make_log_level_config(key: LOG_LEVEL_KEY, level: 'warn'))
+    client = client_with(store, logger_key: LOG_LEVEL_KEY)
+
+    formatter = client.stdlib_formatter
+    now = Time.utc(2026, 4, 22, 12, 0, 0)
+
+    # Below configured warn — suppressed (empty string, which Logger writes
+    # as zero bytes, effectively dropping the line).
+    assert_equal '', formatter.call('DEBUG', now, 'MyApp::Foo', 'hi')
+    assert_equal '', formatter.call('INFO',  now, 'MyApp::Foo', 'hi')
+  end
+
+  def test_formatter_emits_at_or_above_configured_level
+    store = store_with(make_log_level_config(key: LOG_LEVEL_KEY, level: 'warn'))
+    client = client_with(store, logger_key: LOG_LEVEL_KEY)
+
+    formatter = client.stdlib_formatter
+    now = Time.utc(2026, 4, 22, 12, 0, 0)
+
+    refute_equal '', formatter.call('WARN',  now, 'MyApp::Foo', 'hi')
+    refute_equal '', formatter.call('ERROR', now, 'MyApp::Foo', 'hi')
+    refute_equal '', formatter.call('FATAL', now, 'MyApp::Foo', 'hi')
+  end
+
+  def test_formatter_default_format_includes_severity_time_progname_msg
+    store = store_with(make_log_level_config(key: LOG_LEVEL_KEY, level: 'debug'))
+    client = client_with(store, logger_key: LOG_LEVEL_KEY)
+
+    formatter = client.stdlib_formatter
+    now = Time.utc(2026, 4, 22, 12, 34, 56)
+
+    out = formatter.call('INFO', now, 'MyApp::Foo', 'hello world')
+    assert_includes out, 'INFO'
+    assert_includes out, 'MyApp::Foo'
+    assert_includes out, 'hello world'
+    assert out.end_with?("\n"), "formatter output should end with a newline"
+  end
+
+  # ---- progname -> context ---------------------------------------------
+
+  def test_progname_flows_into_logger_context_verbatim
+    # We capture the context the formatter passes to should_log? by replacing
+    # the client's should_log? — avoids building a matcher fixture and lets
+    # us assert the exact context shape the adapter builds.
+    store = store_with(make_log_level_config(key: LOG_LEVEL_KEY, level: 'trace'))
+    client = client_with(store, logger_key: LOG_LEVEL_KEY)
+
+    captured = []
+    client.define_singleton_method(:should_log?) do |logger_path:, desired_level:, contexts: {}|
+      captured << { logger_path: logger_path, desired_level: desired_level }
+      true
+    end
+
+    formatter = client.stdlib_formatter
+    formatter.call('INFO', Time.now, 'HTMLParser', 'x')
+
+    assert_equal 1, captured.size
+    assert_equal 'HTMLParser', captured.first[:logger_path]
+    assert_equal :info,        captured.first[:desired_level]
+  end
+
+  def test_explicit_logger_name_option_overrides_progname
+    store = store_with(make_log_level_config(key: LOG_LEVEL_KEY, level: 'trace'))
+    client = client_with(store, logger_key: LOG_LEVEL_KEY)
+
+    captured = []
+    client.define_singleton_method(:should_log?) do |logger_path:, desired_level:, contexts: {}|
+      captured << logger_path
+      true
+    end
+
+    formatter = client.stdlib_formatter(logger_name: 'ExplicitName')
+    # Pass a different progname — the explicit logger_name should win.
+    formatter.call('INFO', Time.now, 'DifferentProgname', 'x')
+
+    assert_equal 'ExplicitName', captured.first
+  end
+
+  def test_nil_progname_and_no_logger_name_falls_through_as_nil
+    # Ruby's Logger can invoke the formatter with a nil progname; the adapter
+    # should not crash. We pass through nil, and should_log? sees nil. The
+    # evaluator treats missing context values as absent.
+    store = store_with(make_log_level_config(key: LOG_LEVEL_KEY, level: 'trace'))
+    client = client_with(store, logger_key: LOG_LEVEL_KEY)
+
+    captured = []
+    client.define_singleton_method(:should_log?) do |logger_path:, desired_level:, contexts: {}|
+      captured << logger_path
+      true
+    end
+
+    formatter = client.stdlib_formatter
+    formatter.call('INFO', Time.now, nil, 'x')
+
+    assert_nil captured.first
+  end
+
+  # ---- end-to-end with a real ::Logger ---------------------------------
+
+  def test_end_to_end_real_logger_drops_below_and_emits_above
+    store = store_with(make_log_level_config(key: LOG_LEVEL_KEY, level: 'warn'))
+    client = client_with(store, logger_key: LOG_LEVEL_KEY)
+
+    io = StringIO.new
+    logger = ::Logger.new(io)
+    # stdlib Logger has its own static level; set it permissive so our
+    # formatter is the thing actually gating output.
+    logger.level = ::Logger::DEBUG
+    logger.formatter = client.stdlib_formatter(logger_name: 'MyApp::Svc')
+
+    logger.info  'should be dropped'
+    logger.warn  'should be emitted'
+    logger.error 'also emitted'
+
+    out = io.string
+    refute_includes out, 'should be dropped'
+    assert_includes out, 'should be emitted'
+    assert_includes out, 'also emitted'
+  end
+end

data/test/test_telemetry_reporter.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class TestTelemetryReporter < Minitest::Test
+  # Minimal stand-in for Quonfig::HttpConnection that records POSTs.
+  class FakeHttpConnection
+    FakeResponse = Struct.new(:status)
+
+    attr_reader :posts
+
+    def initialize
+      @posts = []
+    end
+
+    def post(path, body)
+      @posts << [path, body]
+      FakeResponse.new(200)
+    end
+  end
+
+  def make_options(telemetry_destination: 'https://telemetry.example.com',
+                   sdk_key: 'qf_sk_development_abc_deadbeef')
+    # Build minimal Options bypassing env-var lookups via explicit overrides.
+    Quonfig::Options.new(
+      sdk_key: sdk_key,
+      environment: 'development',
+      api_urls: ['https://primary.example.com'],
+      enable_sse: false,
+      enable_polling: false,
+      on_init_failure: Quonfig::Options::ON_INITIALIZATION_FAILURE::RETURN,
+      context_upload_mode: :periodic_example
+    ).tap do |opts|
+      opts.instance_variable_set(:@telemetry_destination, telemetry_destination)
+    end
+  end
+
+  def test_sync_posts_combined_events_in_api_telemetry_wire_shape
+    options = make_options
+    fake = FakeHttpConnection.new
+
+    shape_agg = Quonfig::Telemetry::ContextShapeAggregator.new(max_shapes: 100)
+    example_agg = Quonfig::Telemetry::ExampleContextsAggregator.new(max_contexts: 100)
+
+    reporter = Quonfig::Telemetry::TelemetryReporter.new(
+      options: options,
+      instance_hash: 'fake-instance-hash',
+      context_shape_aggregator: shape_agg,
+      example_contexts_aggregator: example_agg,
+      http_connection: fake
+    )
+
+    ctx = Quonfig::Context.new('user' => { 'key' => 'abc', 'age' => 33 })
+    shape_agg.push(ctx)
+    example_agg.record(ctx)
+
+    reporter.sync
+
+    assert_equal 1, fake.posts.size
+    path, body = fake.posts.first
+    assert_equal '/api/v1/telemetry/', path
+
+    # Wire shape: TelemetryEventsSchema
+    assert_equal 'fake-instance-hash', body['instanceHash']
+    assert_kind_of Array, body['events']
+    assert_equal 2, body['events'].size
+
+    shape_event = body['events'].find { |e| e.key?('contextShapes') }
+    example_event = body['events'].find { |e| e.key?('exampleContexts') }
+
+    refute_nil shape_event
+    refute_nil example_event
+
+    # ContextShapesSchema: { shapes: [{ name, fieldTypes }] }
+    shapes = shape_event['contextShapes']['shapes']
+    assert_equal 1, shapes.size
+    assert_equal 'user', shapes[0]['name']
+    assert_equal({ 'key' => 2, 'age' => 1 }, shapes[0]['fieldTypes'])
+
+    # ExampleContextsSchema: { examples: [{ timestamp, contextSet: { contexts: [...] } }] }
+    examples = example_event['exampleContexts']['examples']
+    assert_equal 1, examples.size
+    assert_kind_of Integer, examples[0]['timestamp']
+    contexts_list = examples[0]['contextSet']['contexts']
+    assert_equal 'user', contexts_list[0]['type']
+    assert_equal 'abc', contexts_list[0]['values']['key']
+    assert_equal 33, contexts_list[0]['values']['age']
+  end
+
+  def test_sync_noop_when_aggregators_empty
+    fake = FakeHttpConnection.new
+    reporter = Quonfig::Telemetry::TelemetryReporter.new(
+      options: make_options,
+      instance_hash: 'h',
+      context_shape_aggregator: Quonfig::Telemetry::ContextShapeAggregator.new(max_shapes: 10),
+      example_contexts_aggregator: Quonfig::Telemetry::ExampleContextsAggregator.new(max_contexts: 10),
+      http_connection: fake
+    )
+
+    reporter.sync
+    assert_equal 0, fake.posts.size
+  end
+
+  def test_enabled_requires_sdk_key_and_destination
+    options = make_options(sdk_key: '')
+    reporter = Quonfig::Telemetry::TelemetryReporter.new(
+      options: options,
+      instance_hash: 'h',
+      context_shape_aggregator: Quonfig::Telemetry::ContextShapeAggregator.new(max_shapes: 10)
+    )
+    refute reporter.enabled?
+  end
+
+  def test_record_feeds_both_aggregators
+    fake = FakeHttpConnection.new
+    shape_agg = Quonfig::Telemetry::ContextShapeAggregator.new(max_shapes: 100)
+    example_agg = Quonfig::Telemetry::ExampleContextsAggregator.new(max_contexts: 100)
+
+    reporter = Quonfig::Telemetry::TelemetryReporter.new(
+      options: make_options,
+      instance_hash: 'h',
+      context_shape_aggregator: shape_agg,
+      example_contexts_aggregator: example_agg,
+      http_connection: fake
+    )
+
+    reporter.record(Quonfig::Context.new('user' => { 'key' => 'zzz' }))
+
+    refute_nil shape_agg.drain_event
+    refute_nil example_agg.drain_event
+  end
+
+  def test_sync_posts_evaluation_summaries_event
+    fake = FakeHttpConnection.new
+    summaries_agg = Quonfig::Telemetry::EvaluationSummariesAggregator.new(max_keys: 100)
+
+    reporter = Quonfig::Telemetry::TelemetryReporter.new(
+      options: make_options,
+      instance_hash: 'h',
+      evaluation_summaries_aggregator: summaries_agg,
+      http_connection: fake
+    )
+
+    summaries_agg.record(
+      config_id: 'cid',
+      config_key: 'my-key',
+      config_type: 'config',
+      conditional_value_index: 0,
+      selected_value: 'v',
+      reason: 1
+    )
+
+    reporter.sync
+
+    assert_equal 1, fake.posts.size
+    _path, body = fake.posts.first
+
+    summaries_event = body['events'].find { |e| e.key?('summaries') }
+    refute_nil summaries_event, 'expected a summaries event in the payload'
+
+    inner = summaries_event['summaries']
+    assert_kind_of Array, inner['summaries']
+    counter = inner['summaries'][0]['counters'][0]
+    assert_equal 1, counter['count']
+    assert_equal 1, counter['reason']
+  end
+
+  def test_at_exit_final_drain_posts_pending_batch
+    fake = FakeHttpConnection.new
+    shape_agg = Quonfig::Telemetry::ContextShapeAggregator.new(max_shapes: 100)
+
+    reporter = Quonfig::Telemetry::TelemetryReporter.new(
+      options: make_options,
+      instance_hash: 'h',
+      context_shape_aggregator: shape_agg,
+      http_connection: fake
+    )
+
+    # Simulate evaluations accumulating between sync cycles.
+    shape_agg.push(Quonfig::Context.new('user' => { 'key' => 'x' }))
+
+    # Simulate a Rails SIGTERM: process exits without Client#stop being
+    # called. The reporter's at_exit handler must flush the pending batch.
+    reporter.send(:final_drain_on_exit)
+
+    assert_equal 1, fake.posts.size
+    _path, body = fake.posts.first
+    refute_nil body['events'].find { |e| e.key?('contextShapes') }
+  end
+
+  def test_at_exit_handler_registered_on_start
+    # Guards against regressing the Kernel.at_exit hookup that catches
+    # Rails / Passenger worker SIGTERMs where Client#stop isn't called.
+    fake = FakeHttpConnection.new
+    reporter = Quonfig::Telemetry::TelemetryReporter.new(
+      options: make_options,
+      instance_hash: 'h',
+      context_shape_aggregator: Quonfig::Telemetry::ContextShapeAggregator.new(max_shapes: 10),
+      http_connection: fake,
+      sync_interval: 999 # avoid the background thread firing during the test
+    )
+
+    refute reporter.at_exit_registered?, 'not registered before start'
+    reporter.start
+    assert reporter.at_exit_registered?, 'registered after start'
+  ensure
+    reporter&.stop
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.8
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-22 00:00:00.000000000 Z
+date: 2026-04-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -216,11 +216,14 @@ files:
 - lib/quonfig/duration.rb
 - lib/quonfig/encryption.rb
 - lib/quonfig/error.rb
+- lib/quonfig/errors/decryption_error.rb
 - lib/quonfig/errors/env_var_parse_error.rb
 - lib/quonfig/errors/initialization_timeout_error.rb
+- lib/quonfig/errors/invalid_environment_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/missing_environment_error.rb
 - lib/quonfig/errors/type_mismatch_error.rb
 - lib/quonfig/errors/uninitialized_error.rb
 - lib/quonfig/evaluation.rb
@@ -239,11 +242,16 @@ files:
 - lib/quonfig/semantic_logger_filter.rb
 - lib/quonfig/semver.rb
 - lib/quonfig/sse_config_client.rb
+- lib/quonfig/stdlib_formatter.rb
+- lib/quonfig/telemetry/context_shape.rb
+- lib/quonfig/telemetry/context_shape_aggregator.rb
+- lib/quonfig/telemetry/evaluation_summaries_aggregator.rb
+- lib/quonfig/telemetry/example_contexts_aggregator.rb
+- lib/quonfig/telemetry/telemetry_reporter.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
@@ -264,12 +272,17 @@ files:
 - test/test_caching_http_connection.rb
 - test/test_client.rb
 - test/test_client_network_mode.rb
+- test/test_client_telemetry.rb
 - test/test_config_loader.rb
 - test/test_context.rb
+- test/test_context_shape.rb
+- test/test_context_shape_aggregator.rb
 - test/test_datadir.rb
 - test/test_duration.rb
 - test/test_encryption.rb
+- test/test_evaluation_summaries_aggregator.rb
 - test/test_evaluator.rb
+- test/test_example_contexts_aggregator.rb
 - test/test_exponential_backoff.rb
 - test/test_fixed_size_hash.rb
 - test/test_helper.rb
@@ -282,7 +295,10 @@ files:
 - test/test_resolver.rb
 - test/test_semantic_logger_filter.rb
 - test/test_semver.rb
+- test/test_should_log.rb
 - test/test_sse_config_client.rb
+- test/test_stdlib_formatter.rb
+- test/test_telemetry_reporter.rb
 - test/test_typed_getters.rb
 - test/test_types.rb
 - test/test_weighted_value_resolver.rb