quonfig 0.0.3 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c01dc43b0b300e6f30cd2fad53305feee0cd74229ade2073b44f86777c6c2096
-  data.tar.gz: c7b2191829af4e7b7e72ea36da7a4af6a7a7fb176323ee59a1c1515c4a68c25a
+  metadata.gz: 875b035905394220e72fec4fc1afc3bc62ad6e2975b745098fa4482e1dc348d0
+  data.tar.gz: bd957d0ec077f3a49daf719deb3ea4db64d1b23a69f6264c91385ad21ff06720
 SHA512:
-  metadata.gz: bae99227268f0fb192a398f1b3c7256a7d0a7d4c8aa35208ab6125569dfe95d4af05ee94048ac8dbc662415bd1a07b3ed5c6c86f5d6e75c6919d876538e726f4
-  data.tar.gz: 720a3628d4bbdd75ee432a1ae0d62beccc42b79f95c9afd21ea22a28d815296275e1c2a921b22a45e713934e28fe5d7e2136fedee06f71cbfb41ec2255792033
+  metadata.gz: 9a592d367c361e42e57c42b0ca0929927808e834b5f876545e17436403b11eb5abe08d2996317e5ec5360a1df2228b48a247e22304d6fcda809c3ffee0e3f772
+  data.tar.gz: f3f9b9b1135ab775861164fb89701e6a3cf6b5cb23078d55de89604b13081ce71b7fe00bed192cd9d9134d64fd406fec954efa793e62a2fb558a8ca3cddbec4f

data/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 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
+  previously exposed the logger name under
+  `{ 'quonfig' => { 'logger-name' => '<normalized>' } }`. It now uses
+  `{ 'quonfig-sdk-logging' => { 'key' => '<verbatim name>' } }` so that
+  all SDKs (node, go, ruby, python) share one top-level context name.
+  Any customer rules that match on the old `quonfig.logger-name` property
+  must be rewritten to match `quonfig-sdk-logging.key`.
+- **BREAKING — logger name normalization removed.** The filter no longer
+  converts `MyApp::Services::Auth` → `my_app.services.auth`. Native Ruby
+  class names are passed through verbatim. Rules should target the exact
+  class name (e.g. `PROP_STARTS_WITH_ONE_OF "MyApp::Services::"`).
+- **New: `logger_key` client option** (snake_case) — pass to
+  `Quonfig::Options.new(logger_key: 'log-level.my-app')` or via
+  `Quonfig.init`. Declares the Quonfig config key the higher-level
+  `should_log?` helper evaluates for every log call.
+- **New: `client.should_log?(logger_path:, desired_level:, contexts:)`** —
+  Reforge-style convenience on top of `get`. Evaluates `logger_key` with
+  `{ 'quonfig-sdk-logging' => { 'key' => logger_path } }` merged into the
+  caller's contexts, then compares the returned level to `desired_level`.
+  Raises `Quonfig::Error` if `logger_key` was not set at init. Parallels
+  sdk-node's `shouldLog({loggerPath})` and sdk-go's `ShouldLogPath`.
+- Stage 1 of the per-SDK logger-path rollout (after sdk-node 0.0.14 and
+  sdk-go 0.0.10 shipped the same shape).
+
+## 0.0.4 - 2026-04-22
+
+- **Fix (P0 from test-ruby friction log):** Network mode is now wired through
+  `Client`. Previously, `Quonfig.init` with just `QUONFIG_BACKEND_SDK_KEY`
+  succeeded silently against an empty store; `get` and `enabled?` returned
+  the default for every key because no HTTP fetch ever happened. Now:
+  - On `Client#initialize` (when neither `datadir:` nor `store:` is passed)
+    we do a synchronous HTTP GET against the first `api_urls[0]` (failing
+    over to secondaries), bounded by `initialization_timeout_sec` (default
+    10s). `on_init_failure` decides raise vs continue with empty store.
+  - `enable_sse` (default `true`) subscribes to `{stream.*}/api/v2/sse/config`
+    and applies incremental envelopes to the live `ConfigStore`.
+  - `enable_polling` (default `true`) starts a background poller IFF SSE did
+    not start successfully. This avoids double-fetching when SSE is healthy
+    while still refreshing in proxied / SSE-blocked environments. Interval
+    comes from `Options#poll_interval` (default 60s).
+  - `Client#stop` now closes the SSE connection and kills the poll thread.
+- Adds `Options#poll_interval` (default 60s); previously missing from the
+  Options surface despite being documented.
+- `ConfigLoader` now populates the `ConfigStore` directly on each successful
+  fetch, so the Evaluator/Resolver see the new configs immediately (wire
+  path matches sdk-node/sdk-go — `ConfigResponse` envelope JSON). (qfg-s7h)
+
 ## 0.0.3 - 2026-04-22
 
 - **Release plumbing only** — no functional changes. Renames the release

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.3
+0.0.6

data/lib/quonfig/client.rb

@@ -1,20 +1,27 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'timeout'
 
 module Quonfig
   # Public Quonfig SDK client.
   #
-  # Wires the new JSON stack: Quonfig::ConfigStore + Quonfig::Evaluator +
-  # Quonfig::Resolver. The legacy protobuf-driven ConfigClient/ConfigResolver
-  # path was removed in qfg-dk6.32. Network-mode (HTTP fetch + SSE updates) is
-  # not yet wired through Client; today the supported entry points are
-  # +datadir:+ (offline workspace) and +store:+ (caller-supplied
-  # Quonfig::ConfigStore, used by tests).
+  # Wires the JSON stack: Quonfig::ConfigStore + Quonfig::Evaluator +
+  # Quonfig::Resolver. Three modes are supported:
+  #
+  # 1. +datadir:+ (offline) -- load a workspace from the local filesystem.
+  # 2. +store:+ (test harness) -- caller-supplied ConfigStore, no I/O.
+  # 3. network mode (default) -- HTTP fetch from +api_urls+ populates the
+  #    ConfigStore, then (if enabled) an SSE subscription keeps it live.
+  #
+  # Network mode is the happy path for production SDK usage. The protobuf
+  # stack was retired in qfg-dk6.32; HTTP + SSE were wired back through Client
+  # in qfg-s7h.
   class Client
     LOG = Quonfig::InternalLogger.new(self)
 
-    attr_reader :options, :resolver, :store, :evaluator, :instance_hash
+    attr_reader :options, :resolver, :store, :evaluator, :instance_hash,
+                :config_loader
 
     def initialize(options = nil, store: nil, **option_kwargs)
       @options =
@@ -27,10 +34,22 @@ module Quonfig
         end
       @global_context = normalize_context(@options.global_context)
       @instance_hash = SecureRandom.uuid
-      @store = store || build_store
+      @store = store || Quonfig::ConfigStore.new
       @evaluator = Quonfig::Evaluator.new(@store, env_id: @options.environment)
       @resolver = Quonfig::Resolver.new(@store, @evaluator)
       @semantic_logger_filters = {}
+      @sse_client = nil
+      @poll_thread = nil
+      @stopped = false
+
+      # If the caller injected a store, we're in test/bootstrap mode; skip I/O.
+      return if store
+
+      if @options.datadir
+        load_datadir_into_store
+      else
+        initialize_network_mode
+      end
     end
 
     # ---- Lookup --------------------------------------------------------
@@ -106,13 +125,104 @@ 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.
+    def logger_key
+      @options.logger_key
+    end
+
+    # Higher-level log-level check — a convenience on top of the primitive
+    # +get+. Evaluates the client's +logger_key+ config and returns whether
+    # a message at +desired_level+ should be emitted for +logger_path+.
+    #
+    # The SDK injects +logger_path+ under the +quonfig-sdk-logging+ named
+    # context with property +key+ so a single log-level config can drive
+    # per-logger overrides via the normal rule engine (e.g.
+    # PROP_STARTS_WITH_ONE_OF "MyApp::Services::").
+    #
+    # +logger_path+ is passed through verbatim — the SDK does not normalize
+    # it. Callers may pass any identifier shape their host language prefers
+    # (dotted, colon, slash, etc.) and author matching rules in the config
+    # against that exact shape.
+    #
+    # Parallels sdk-node's +shouldLog({loggerPath})+ and sdk-go's
+    # +ShouldLogPath+.
+    #
+    # Raises +Quonfig::Error+ if +logger_key+ was not set on the client —
+    # use +semantic_logger_filter(config_key:)+ directly if you want to
+    # evaluate a specific key without declaring it at init time.
+    #
+    # @param logger_path [String] native logger name (typically a class name).
+    # @param desired_level [Symbol, String] the level the caller wants to
+    #   emit at (:trace, :debug, :info, :warn, :error, :fatal).
+    # @param contexts [Hash] optional extra context to merge with the
+    #   injected logger context.
+    # @return [Boolean] true if the message should be emitted.
+    def should_log?(logger_path:, desired_level:, contexts: {})
+      unless logger_key
+        raise Quonfig::Error,
+              'logger_key must be set at init to use should_log?(logger_path:, ...). ' \
+              'Pass `logger_key:` to Quonfig::Options.new, or call ' \
+              'semantic_logger_filter(config_key:) / get(config_key) directly.'
+      end
+
+      logger_context = {
+        Quonfig::SemanticLoggerFilter::LOGGER_CONTEXT_NAME => {
+          Quonfig::SemanticLoggerFilter::LOGGER_CONTEXT_KEY_PROP => logger_path
+        }
+      }
+      merged = merge_contexts(normalize_context(contexts), logger_context)
+
+      configured = get(logger_key, nil, merged)
+      return true if configured.nil?
+
+      desired_severity = Quonfig::SemanticLoggerFilter::LEVELS[normalize_log_level(desired_level)] ||
+                         Quonfig::SemanticLoggerFilter::LEVELS[:debug]
+      min_severity     = Quonfig::SemanticLoggerFilter::LEVELS[normalize_log_level(configured)] ||
+                         Quonfig::SemanticLoggerFilter::LEVELS[:debug]
+      desired_severity >= min_severity
+    end
+
     def on_update(&block)
       @on_update = block
     end
 
     def stop
-      # No background threads in datadir mode; placeholder for the future
-      # SSE/poll path so callers can use this method symmetrically.
+      @stopped = true
+      begin
+        @sse_client&.close
+      rescue StandardError => e
+        LOG.debug "Error closing SSE client: #{e.message}"
+      end
+      @sse_client = nil
+
+      thread = @poll_thread
+      @poll_thread = nil
+      thread&.kill
     end
 
     def fork
@@ -125,11 +235,97 @@ module Quonfig
 
     private
 
-    def build_store
-      if @options.datadir
-        Quonfig::Datadir.load_store(@options.datadir, @options.environment)
-      else
-        Quonfig::ConfigStore.new
+    def load_datadir_into_store
+      envelope = Quonfig::Datadir.load_envelope(@options.datadir, @options.environment)
+      envelope.configs.each { |cfg| @store.set(cfg['key'], cfg) }
+    end
+
+    # Initialize network mode: sync HTTP fetch (bounded by
+    # initialization_timeout_sec) then start SSE + polling as requested.
+    def initialize_network_mode
+      if @options.sdk_key.nil? || @options.sdk_key.to_s.strip.empty?
+        raise Quonfig::Errors::InvalidSdkKeyError, @options.sdk_key
+      end
+
+      @config_loader = Quonfig::ConfigLoader.new(@store, @options)
+
+      perform_initial_fetch
+
+      sse_started = @options.enable_sse && start_sse
+
+      # Polling is a fallback: if SSE is off or failed to start, poll. This
+      # avoids double-work when SSE is healthy but still refreshes the store
+      # in environments that block SSE (corporate proxies, Lambda, etc.).
+      start_polling if @options.enable_polling && !sse_started
+    end
+
+    def perform_initial_fetch
+      timeout = @options.initialization_timeout_sec || 10
+      result = :failed
+
+      begin
+        Timeout.timeout(timeout) do
+          result = @config_loader.fetch!
+        end
+      rescue Timeout::Error
+        handle_init_failure(
+          Quonfig::Errors::InitializationTimeoutError.new(timeout, nil)
+        )
+        return
+      end
+
+      handle_init_failure(RuntimeError.new('Config fetch failed against all api_urls')) if result == :failed
+    end
+
+    def handle_init_failure(err)
+      if @options.on_init_failure == Quonfig::Options::ON_INITIALIZATION_FAILURE::RETURN
+        LOG.warn "[quonfig] Initialization did not complete cleanly; continuing with empty store: #{err.message}"
+        return
+      end
+
+      raise err
+    end
+
+    # Returns true if SSE started successfully, false otherwise. A false here
+    # signals the caller to fall back to polling.
+    def start_sse
+      return false if @options.sse_api_urls.nil? || @options.sse_api_urls.empty?
+
+      @sse_client = Quonfig::SSEConfigClient.new(@options, @config_loader)
+      @sse_client.start do |envelope, _event, _source|
+        next if @stopped
+        begin
+          @config_loader.apply_envelope(envelope)
+          @on_update&.call
+        rescue StandardError => e
+          LOG.warn "[quonfig] Error applying SSE envelope: #{e.message}"
+        end
+      end
+      true
+    rescue StandardError => e
+      LOG.warn "[quonfig] SSE start failed: #{e.message}"
+      @sse_client = nil
+      false
+    end
+
+    def start_polling
+      poll_interval = @options.respond_to?(:poll_interval) && @options.poll_interval ? @options.poll_interval : 60
+      return if poll_interval <= 0
+
+      @poll_thread = Thread.new do
+        Thread.current.name = 'quonfig-poller'
+        loop do
+          break if @stopped
+          sleep poll_interval
+          break if @stopped
+
+          begin
+            @config_loader.fetch!
+            @on_update&.call
+          rescue StandardError => e
+            LOG.warn "[quonfig] Polling error: #{e.message}"
+          end
+        end
       end
     end
 
@@ -164,6 +360,14 @@ module Quonfig
       merged
     end
 
+    def normalize_log_level(level)
+      case level
+      when Symbol then level.downcase
+      when String then level.downcase.to_sym
+      else level
+      end
+    end
+
     def handle_missing(key, default)
       return default if default != NO_DEFAULT_PROVIDED
 

data/lib/quonfig/config_loader.rb

@@ -3,26 +3,54 @@
 require 'json'
 
 module Quonfig
+  # Fetches config envelopes from the Quonfig delivery API and installs them
+  # into a ConfigStore.
+  #
+  # Wire format matches sdk-node's Transport + ConfigStore:
+  #   GET /api/v2/configs
+  #     -> 200 { "configs": [...], "meta": { "version": "...", "environment": "..." } }
+  #     -> 304 Not Modified (ETag honored via If-None-Match)
+  #
+  # The fetch is synchronous; Client is responsible for timing out the initial
+  # fetch per `initialization_timeout_sec`.
   class ConfigLoader
     LOG = Quonfig::InternalLogger.new(self)
 
     CONFIGS_PATH = '/api/v2/configs'
 
-    attr_reader :etag
+    attr_reader :etag, :version, :environment_id
+
+    # +store+: the Quonfig::ConfigStore to populate on successful fetch.
+    # +options+: a Quonfig::Options instance (supplies sdk_key + config_api_urls).
+    # +logger+: optional logger override (defaults to module LOG).
+    #
+    # Backward compat: callers that pass a single +base_client+ (mock client
+    # used by tests that expects `.options`) are still supported.
+    def initialize(store_or_base_client, options = nil, logger: nil)
+      if options.nil? && store_or_base_client.respond_to?(:options)
+        # Legacy shape: ConfigLoader.new(base_client)
+        @options = store_or_base_client.options
+        @store = nil
+      else
+        @store = store_or_base_client
+        @options = options
+      end
 
-    def initialize(base_client)
-      @base_client = base_client
-      @options = base_client.options
       @api_config = Concurrent::Map.new
       @etag = nil
+      @version = nil
+      @environment_id = nil
+      @logger = logger || LOG
     end
 
     # Fetch configs from /api/v2/configs with ETag / If-None-Match caching.
+    # On 200 responses, installs the envelope into the attached ConfigStore
+    # (if one was provided).
     #
     # Returns one of:
-    #   :updated       — 200 response; @api_config and @etag replaced
-    #   :not_modified  — 304 response; cache still valid
-    #   :failed        — every configured source failed
+    #   :updated       -- 200 response; store replaced
+    #   :not_modified  -- 304 response; store untouched
+    #   :failed        -- every configured source failed
     def fetch!
       Array(@options.config_api_urls).each do |api_url|
         result = fetch_from(api_url)
@@ -31,6 +59,12 @@ module Quonfig
       :failed
     end
 
+    # Apply a ConfigEnvelope (from SSE) to the store. Called by the SSE client
+    # when a new event arrives.
+    def apply_envelope(envelope)
+      install_envelope(envelope, source: :sse)
+    end
+
     def calc_config
       rtn = {}
       @api_config.each_key do |k|
@@ -59,21 +93,24 @@ module Quonfig
       when 200
         new_etag = response.headers['ETag'] || response.headers['etag']
         envelope = parse_envelope(response.body)
-        replace_api_config(envelope, source)
+        install_envelope(envelope, source: source)
         @etag = new_etag
         :updated
       when 304
-        LOG.debug "Configs not modified (304) from #{source}"
+        @logger.debug "Configs not modified (304) from #{source}"
         :not_modified
+      when 401, 403
+        @logger.warn "Config fetch rejected (#{response.status}) from #{source}: #{short_body(response)}"
+        :failed
       else
-        LOG.info "Config fetch failed: status #{response.status} from #{source}"
+        @logger.info "Config fetch failed: status #{response.status} from #{source}"
         :failed
       end
     rescue Faraday::ConnectionFailed => e
-      LOG.debug "Connection failure fetching configs from #{source}: #{e.message}"
+      @logger.debug "Connection failure fetching configs from #{source}: #{e.message}"
       :failed
     rescue StandardError => e
-      LOG.warn "Unexpected error fetching configs from #{source}: #{e.message}"
+      @logger.warn "Unexpected error fetching configs from #{source}: #{e.message}"
       :failed
     end
 
@@ -85,7 +122,14 @@ module Quonfig
       )
     end
 
-    def replace_api_config(envelope, source)
+    def short_body(response)
+      return '' if response.body.nil?
+      str = response.body.to_s
+      str.length > 200 ? str[0, 200] + '...' : str
+    end
+
+    def install_envelope(envelope, source:)
+      # Update internal tracking map (for legacy callers / introspection).
       next_map = Concurrent::Map.new
       envelope.configs.each do |cfg|
         key = config_key(cfg)
@@ -93,6 +137,24 @@ module Quonfig
         next_map[key] = { source: source, config: cfg }
       end
       @api_config = next_map
+
+      meta = envelope.meta || {}
+      @version = meta['version'] || meta[:version] || @version
+      @environment_id = meta['environment'] || meta[:environment] || @environment_id
+
+      # Replace the live store atomically.
+      return if @store.nil?
+
+      new_keys = next_map.keys.to_set
+      old_keys = @store.keys.to_set
+      # Drop keys that disappeared server-side.
+      (old_keys - new_keys).each { |k| @store.delete(k) } if @store.respond_to?(:delete)
+
+      envelope.configs.each do |cfg|
+        key = config_key(cfg)
+        next if key.nil?
+        @store.set(key, cfg)
+      end
     end
 
     def config_key(cfg)

data/lib/quonfig/config_store.rb

@@ -23,6 +23,10 @@ module Quonfig
       @lock.with_write_lock { @configs[key] = config }
     end
 
+    def delete(key)
+      @lock.with_write_lock { @configs.delete(key) }
+    end
+
     def clear
       @lock.with_write_lock do
         @configs.keys.each { |k| @configs.delete(k) }

data/lib/quonfig/options.rb

@@ -18,7 +18,9 @@ module Quonfig
     attr_reader :datadir
     attr_reader :enable_sse
     attr_reader :enable_polling
+    attr_reader :poll_interval
     attr_reader :global_context
+    attr_reader :logger_key
     attr_accessor :is_fork
 
     module ON_INITIALIZATION_FAILURE
@@ -60,6 +62,7 @@ module Quonfig
       datadir: ENV['QUONFIG_DIR'],
       enable_sse: true,
       enable_polling: true,
+      poll_interval: 60,
       on_no_default: ON_NO_DEFAULT::RAISE,
       initialization_timeout_sec: 10,
       on_init_failure: ON_INITIALIZATION_FAILURE::RAISE,
@@ -70,13 +73,15 @@ module Quonfig
       collect_evaluation_summaries: true,
       collect_max_evaluation_summaries: DEFAULT_MAX_EVAL_SUMMARIES,
       allow_telemetry_in_local_mode: false,
-      global_context: {}
+      global_context: {},
+      logger_key: nil
     )
       @sdk_key = sdk_key
       @environment = environment
       @datadir = datadir
       @enable_sse = enable_sse
       @enable_polling = enable_polling
+      @poll_interval = poll_interval
       @on_no_default = on_no_default
       @initialization_timeout_sec = initialization_timeout_sec
       @on_init_failure = on_init_failure
@@ -88,6 +93,7 @@ module Quonfig
       @allow_telemetry_in_local_mode = allow_telemetry_in_local_mode
       @is_fork = false
       @global_context = global_context
+      @logger_key = logger_key
 
       # defaults that may be overridden by context_upload_mode
       @collect_shapes = false

data/lib/quonfig/semantic_logger_filter.rb

@@ -2,18 +2,27 @@
 
 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.
+  # whose rules target the logger via the
+  # +quonfig-sdk-logging.key+ context property.
   #
   # Usage:
-  #   filter = client.semantic_logger_filter(config_key: 'log-levels.my-app')
+  #   filter = client.semantic_logger_filter(config_key: 'log-level.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.
+  # The filter exposes the SemanticLogger logger name (which is typically the
+  # native Ruby class name, e.g. +"MyApp::Services::Auth"+) under the
+  # +quonfig-sdk-logging+ named context with property +key+ so customer rules
+  # can discriminate per-logger via PROP_STARTS_WITH_ONE_OF /
+  # PROP_IS_ONE_OF etc. Lookup is O(1): one +client.get+ call per log line.
+  #
+  # Logger names are passed through verbatim — there is no snake_case
+  # normalization. Matching rules should target the exact class name
+  # (e.g. +MyApp::+, +MyApp::Services::Auth+).
+  #
+  # The constants +LOGGER_CONTEXT_NAME+ and +LOGGER_CONTEXT_KEY_PROP+ are
+  # load-bearing: they match +QUONFIG_SDK_LOGGING_CONTEXT_NAME+ in sdk-node
+  # and sdk-go, and are consumed by api-telemetry's example-context
+  # auto-capture. Do not rename in isolation.
   class SemanticLoggerFilter
     LEVELS = {
       trace: 0,
@@ -24,7 +33,8 @@ module Quonfig
       fatal: 5
     }.freeze
 
-    LOGGER_NAME_CONTEXT_KEY = 'quonfig.logger-name'
+    LOGGER_CONTEXT_NAME     = 'quonfig-sdk-logging'
+    LOGGER_CONTEXT_KEY_PROP = 'key'
 
     def self.semantic_logger_loaded?
       defined?(SemanticLogger)
@@ -50,22 +60,10 @@ module Quonfig
       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) } }
+      { LOGGER_CONTEXT_NAME => { LOGGER_CONTEXT_KEY_PROP => log.name.to_s } }
     end
 
     def normalize_level(level)

data/lib/quonfig/sse_config_client.rb

@@ -66,13 +66,14 @@ module Quonfig
 
     def connect(&load_configs)
       url = "#{source}/api/v2/sse/config"
-      @logger.debug "SSE Streaming Connect to #{url} start_at #{@config_loader.highwater_mark}"
+      cursor = current_cursor
+      @logger.debug "SSE Streaming Connect to #{url} start_at #{cursor.inspect}"
 
       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),
+                      last_event_id: cursor,
                       logger: Quonfig::InternalLogger.new(SSE::Client)) do |client|
         client.on_event do |event|
           if event.data.nil? || event.data.empty?
@@ -131,5 +132,25 @@ module Quonfig
 
       @prefab_options.sse_api_urls[@source_index]
     end
+
+    # Compute a Last-Event-ID to resume the stream from. Three sources, in
+    # priority order:
+    #   1. config_loader.version  -- string ETag from last HTTP fetch (new path)
+    #   2. config_loader.highwater_mark -- legacy numeric cursor
+    #   3. nil -- no prior state; stream from HEAD
+    def current_cursor
+      if @config_loader.respond_to?(:version)
+        v = @config_loader.version
+        return v if v.is_a?(String) && !v.empty?
+      end
+
+      if @config_loader.respond_to?(:highwater_mark)
+        hw = @config_loader.highwater_mark
+        return hw.to_s if hw.is_a?(Numeric) && hw.positive?
+        return hw if hw.is_a?(String) && !hw.empty?
+      end
+
+      nil
+    end
   end
 end

data/lib/quonfig.rb

@@ -51,6 +51,7 @@ require 'quonfig/context'
 require 'quonfig/client'
 require 'quonfig/bound_client'
 require 'quonfig/semantic_logger_filter'
+require 'quonfig/stdlib_formatter'
 require 'quonfig/quonfig'
 require 'quonfig/murmer3'
 require 'quonfig/semver'

data/quonfig.gemspec

@@ -104,6 +104,7 @@ Gem::Specification.new do |s|
     "test/test_bound_client.rb",
     "test/test_caching_http_connection.rb",
     "test/test_client.rb",
+    "test/test_client_network_mode.rb",
     "test/test_config_loader.rb",
     "test/test_context.rb",
     "test/test_datadir.rb",

data/test/test_client_network_mode.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+require 'webrick'
+require 'json'
+
+# Verifies Client#initialize (qfg-s7h) wires HTTP fetch + ConfigStore together
+# so `Quonfig.get(...)` / `Quonfig.enabled?(...)` return real values — not the
+# defaults — when only an `sdk_key:` + `api_urls:` are supplied. This is the
+# regression test for the P0 documented in test-ruby/FRICTION.md where
+# network-mode was accepted but silently ignored in v0.0.3.
+class TestClientNetworkMode < Minitest::Test
+  PORT = 18_094
+
+  SAMPLE_CONFIG = {
+    'id' => 'c1',
+    'key' => 'log-levels.test-ruby',
+    'type' => 'log_level',
+    'valueType' => 'log_level',
+    'sendToClientSdk' => false,
+    'default' => {
+      'rules' => [
+        {
+          'criteria' => [{ 'operator' => 'ALWAYS_TRUE' }],
+          'value' => { 'type' => 'log_level', 'value' => 'WARN' }
+        }
+      ]
+    }
+  }.freeze
+
+  def setup
+    super
+    @server = nil
+    @fetch_count = 0
+  end
+
+  def teardown
+    @server&.shutdown
+    super
+  end
+
+  def start_server
+    log = WEBrick::Log.new(StringIO.new)
+    @server = WEBrick::HTTPServer.new(
+      Port: PORT, Logger: log, AccessLog: []
+    )
+    @server.mount_proc '/api/v2/configs' do |_req, res|
+      @fetch_count += 1
+      res.status = 200
+      res['Content-Type'] = 'application/json'
+      res['ETag'] = "v#{@fetch_count}"
+      res.body = JSON.generate(
+        'configs' => [SAMPLE_CONFIG],
+        'meta' => { 'version' => "v#{@fetch_count}", 'environment' => 'dev' }
+      )
+    end
+    Thread.new { @server.start }
+    # Wait for server to be ready.
+    50.times do
+      break if tcp_open?
+      sleep 0.05
+    end
+  end
+
+  def tcp_open?
+    require 'socket'
+    TCPSocket.new('127.0.0.1', PORT).tap(&:close)
+    true
+  rescue StandardError
+    false
+  end
+
+  def test_initialize_fetches_configs_from_api_urls_and_populates_store
+    start_server
+
+    client = Quonfig::Client.new(
+      sdk_key: 'test-key',
+      api_urls: ["http://127.0.0.1:#{PORT}"],
+      enable_sse: false,
+      enable_polling: false
+    )
+
+    assert_equal 1, @fetch_count, 'expected exactly one HTTP fetch during init'
+    assert_includes client.keys, 'log-levels.test-ruby'
+    assert_equal 'WARN', client.get('log-levels.test-ruby', 'default')
+  ensure
+    client&.stop
+  end
+
+  def test_initialize_raises_on_fetch_failure_by_default
+    # No server started -> connection refused everywhere
+    assert_raises(RuntimeError, Quonfig::Errors::InitializationTimeoutError) do
+      Quonfig::Client.new(
+        sdk_key: 'test-key',
+        api_urls: ['http://127.0.0.1:1'], # almost certainly unreachable
+        enable_sse: false,
+        enable_polling: false,
+        initialization_timeout_sec: 2
+      )
+    end
+  end
+
+  def test_initialize_returns_empty_store_when_on_init_failure_is_return
+    client = Quonfig::Client.new(
+      sdk_key: 'test-key',
+      api_urls: ['http://127.0.0.1:1'],
+      enable_sse: false,
+      enable_polling: false,
+      initialization_timeout_sec: 2,
+      on_init_failure: Quonfig::Options::ON_INITIALIZATION_FAILURE::RETURN
+    )
+
+    assert_empty client.keys
+    assert_logged [/Initialization did not complete cleanly/]
+  ensure
+    client&.stop
+  end
+
+  def test_initialize_skips_network_when_store_injected
+    # store: passed -> Client should not try any I/O. Unreachable URL must
+    # be fine when a store is injected.
+    store = Quonfig::ConfigStore.new
+    client = Quonfig::Client.new(
+      Quonfig::Options.new(
+        sdk_key: 'test-key',
+        api_urls: ['http://127.0.0.1:1'],
+        enable_sse: false,
+        enable_polling: false
+      ),
+      store: store
+    )
+    assert_same store, client.store
+  ensure
+    client&.stop
+  end
+end

data/test/test_semantic_logger_filter.rb

@@ -3,16 +3,20 @@
 require 'test_helper'
 require 'semantic_logger'
 
-# Verifies the corrected design: ONE Quonfig config gates many loggers.
-# The filter passes `quonfig.logger-name` as a context property so customer
-# rules can target `PROP_STARTS_WITH_ONE_OF my_app.db` etc.
+# Verifies the SemanticLoggerFilter: ONE Quonfig config gates many loggers.
+# The filter injects the native SemanticLogger logger name under the
+# `quonfig-sdk-logging` context (keyed at `.key`) so customer rules can target
+# `PROP_STARTS_WITH_ONE_OF MyApp::` etc.
+#
+# Breaking change in 0.0.5: context key was renamed from `quonfig.logger-name`
+# (dotted snake_case, flat) to `quonfig-sdk-logging.key` (nested, verbatim
+# class name). Normalization was removed — logger names are passed through
+# as-is.
 class TestSemanticLoggerFilter < Minitest::Test
   CONFIG_KEY = 'log-levels.my-app'
 
   # FakeClient lets us assert the exact key + context the filter passes to
-  # the SDK without standing up a full datadir. The single-key contract is
-  # the *specific mechanism* this bead is verifying — if the filter ever
-  # regresses to a per-logger key, this captured request goes wrong.
+  # the SDK without standing up a full datadir.
   class FakeClient
     attr_reader :calls
 
@@ -43,7 +47,7 @@ class TestSemanticLoggerFilter < Minitest::Test
     assert_equal 1, client.calls.size
     assert_equal CONFIG_KEY, client.calls.first[:key]
     ctx = client.calls.first[:context]
-    assert_equal({ 'quonfig' => { 'logger-name' => 'my_app.foo.bar' } }, ctx)
+    assert_equal({ 'quonfig-sdk-logging' => { 'key' => 'MyApp::Foo::Bar' } }, ctx)
   end
 
   def test_passes_through_when_level_meets_configured_minimum
@@ -71,19 +75,22 @@ class TestSemanticLoggerFilter < Minitest::Test
     assert_equal true, filter.call(make_log('Anything', :debug))
   end
 
-  def test_logger_name_normalization
+  def test_logger_name_passed_through_verbatim
+    # Normalization is gone. Native Ruby class names are preserved as-is,
+    # which matches how sdk-node and sdk-go pass the logger path.
     filter, client = filter_for(:debug)
 
-    {
-      'MyApp::Foo::Bar' => 'my_app.foo.bar',
-      'HTMLParser'      => 'html_parser',
-      'foo'             => 'foo',
-      'A::B::CDPath'    => 'a.b.cd_path'
-    }.each do |raw, expected|
+    [
+      'MyApp::Foo::Bar',
+      'HTMLParser',
+      'foo',
+      'A::B::CDPath',
+      'MyApp::Services::Auth'
+    ].each do |raw|
       client.calls.clear
       filter.call(make_log(raw, :info))
-      assert_equal expected, client.calls.first[:context]['quonfig']['logger-name'],
-                   "normalize(#{raw.inspect}) should be #{expected.inspect}"
+      assert_equal raw, client.calls.first[:context]['quonfig-sdk-logging']['key'],
+                   "logger name should be passed through verbatim: #{raw.inspect}"
     end
   end
 
@@ -100,6 +107,20 @@ class TestSemanticLoggerFilter < Minitest::Test
                  'Filter should call exactly the configured key, never derived per-logger keys'
   end
 
+  def test_normalize_method_is_gone
+    # The old normalize() method converted "MyApp::Foo" → "my_app.foo".
+    # It is intentionally removed so callers see native Ruby class names in
+    # context telemetry and rule matching.
+    refute Quonfig::SemanticLoggerFilter.instance_methods.include?(:normalize),
+           'normalize() should be removed — logger names are passed through as-is'
+  end
+
+  def test_context_key_constant_is_new_shape
+    # Sanity check that the context key constant exposes the new shape.
+    assert_equal 'quonfig-sdk-logging', Quonfig::SemanticLoggerFilter::LOGGER_CONTEXT_NAME
+    assert_equal 'key',                 Quonfig::SemanticLoggerFilter::LOGGER_CONTEXT_KEY_PROP
+  end
+
   def test_all_six_levels_mapped_correctly
     expected = { trace: 0, debug: 1, info: 2, warn: 3, error: 4, fatal: 5 }
     assert_equal expected, Quonfig::SemanticLoggerFilter::LEVELS

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.6
 platform: ruby
 authors:
 - Jeff Dwyer
@@ -263,6 +263,7 @@ files:
 - test/test_bound_client.rb
 - test/test_caching_http_connection.rb
 - test/test_client.rb
+- test/test_client_network_mode.rb
 - test/test_config_loader.rb
 - test/test_context.rb
 - test/test_datadir.rb