quonfig 0.0.2

data/lib/quonfig/bound_client.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Quonfig
+  # Immutable context-bound view over a Quonfig::Client. Every lookup uses the
+  # bound context as the jit_context passed down to the resolver.
+  class BoundClient
+    attr_reader :client, :context
+
+    def initialize(client, context)
+      @client = client
+      @context = context || {}
+      freeze
+    end
+
+    def get_string(key, default: NO_DEFAULT_PROVIDED)
+      @client.get_string(key, default: default, context: @context)
+    end
+
+    def get_int(key, default: NO_DEFAULT_PROVIDED)
+      @client.get_int(key, default: default, context: @context)
+    end
+
+    def get_float(key, default: NO_DEFAULT_PROVIDED)
+      @client.get_float(key, default: default, context: @context)
+    end
+
+    def get_bool(key, default: NO_DEFAULT_PROVIDED)
+      @client.get_bool(key, default: default, context: @context)
+    end
+
+    def get_string_list(key, default: NO_DEFAULT_PROVIDED)
+      @client.get_string_list(key, default: default, context: @context)
+    end
+
+    def get_duration(key, default: NO_DEFAULT_PROVIDED)
+      @client.get_duration(key, default: default, context: @context)
+    end
+
+    def get_json(key, default: NO_DEFAULT_PROVIDED)
+      @client.get_json(key, default: default, context: @context)
+    end
+
+    def enabled?(feature_name)
+      @client.enabled?(feature_name, @context)
+    end
+
+    # Returns a new BoundClient whose bound context is the merge of this
+    # bound context and +additional+. Merge is one level deep per named
+    # context (mirrors sdk-node's mergeContexts): later values override
+    # earlier within the same named context; keys unique to each side are
+    # preserved.
+    def in_context(additional)
+      self.class.new(@client, merge_contexts(@context, additional || {}))
+    end
+
+    def inspect
+      "#<Quonfig::BoundClient context=#{@context.inspect}>"
+    end
+
+    private
+
+    def merge_contexts(left, right)
+      merged = {}
+      left.each  { |name, ctx| merged[name] = ctx.dup }
+      right.each do |name, ctx|
+        merged[name] = merged[name] ? merged[name].merge(ctx) : ctx.dup
+      end
+      merged
+    end
+  end
+end

data/lib/quonfig/caching_http_connection.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Quonfig
+  class CachingHttpConnection
+    CACHE_SIZE = 2.freeze
+    CacheEntry = Struct.new(:data, :etag, :expires_at)
+
+    class << self
+      def cache
+        @cache ||= FixedSizeHash.new(CACHE_SIZE)
+      end
+
+      def reset_cache!
+        @cache = FixedSizeHash.new(CACHE_SIZE)
+      end
+    end
+
+    def initialize(uri, api_key)
+      @connection = HttpConnection.new(uri, api_key)
+    end
+
+    def get(path)
+      now = Time.now.to_i
+      cache_key = "#{@connection.uri}#{path}"
+      cached = self.class.cache[cache_key]
+
+      # Check if we have a valid cached response
+      if cached&.data && cached.expires_at && now < cached.expires_at
+        return Faraday::Response.new(
+          status: 200,
+          body: cached.data,
+          response_headers: {
+            'ETag' => cached.etag,
+            'X-Cache' => 'HIT',
+            'X-Cache-Expires-At' => cached.expires_at.to_s
+          }
+        )
+      end
+
+      # Make request with conditional GET if we have an ETag
+      response = if cached&.etag
+                   @connection.get(path, { 'If-None-Match' => cached.etag })
+                 else
+                   @connection.get(path)
+                 end
+
+      # Handle 304 Not Modified
+      if response.status == 304 && cached&.data
+        return Faraday::Response.new(
+          status: 200,
+          body: cached.data,
+          response_headers: {
+            'ETag' => cached.etag,
+            'X-Cache' => 'HIT',
+            'X-Cache-Expires-At' => cached.expires_at.to_s
+          }
+        )
+      end
+
+      # Parse caching headers
+      cache_control = response.headers['Cache-Control'].to_s
+      etag = response.headers['ETag']
+
+      # Always add X-Cache header
+      response.headers['X-Cache'] = 'MISS'
+
+      # Don't cache if no-store is present
+      return response if cache_control.include?('no-store')
+
+      # Calculate expiration
+      max_age = cache_control.match(/max-age=(\d+)/)&.captures&.first&.to_i
+      expires_at = max_age ? now + max_age : nil
+
+      # Cache the response if we have caching headers
+      if etag || expires_at
+        self.class.cache[cache_key] = CacheEntry.new(
+          response.body,
+          etag,
+          expires_at
+        )
+      end
+
+      response
+    end
+
+    # Delegate other methods to the underlying connection
+    def post(path, body)
+      @connection.post(path, body)
+    end
+
+    def uri
+      @connection.uri
+    end
+  end
+end

data/lib/quonfig/client.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require 'json'
+
+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).
+  class Client
+    LOG = Quonfig::InternalLogger.new(self)
+
+    attr_reader :options, :resolver, :store, :evaluator, :instance_hash
+
+    def initialize(options = nil, store: nil, **option_kwargs)
+      @options =
+        if options.is_a?(Quonfig::Options)
+          options
+        elsif options.is_a?(Hash)
+          Quonfig::Options.new(options.merge(option_kwargs))
+        else
+          Quonfig::Options.new(option_kwargs)
+        end
+      @global_context = normalize_context(@options.global_context)
+      @instance_hash = SecureRandom.uuid
+      @store = store || build_store
+      @evaluator = Quonfig::Evaluator.new(@store, env_id: @options.environment)
+      @resolver = Quonfig::Resolver.new(@store, @evaluator)
+      @semantic_logger_filters = {}
+    end
+
+    # ---- Lookup --------------------------------------------------------
+
+    def get(key, default = NO_DEFAULT_PROVIDED, jit_context = NO_DEFAULT_PROVIDED)
+      ctx = build_context(jit_context)
+      result = @resolver.get(key, ctx)
+      return handle_missing(key, default) if result.nil?
+
+      result.unwrapped_value
+    end
+
+    def get_string(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
+      typed_get(key, String, default: default, context: context)
+    end
+
+    def get_int(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
+      typed_get(key, Integer, default: default, context: context)
+    end
+
+    def get_float(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
+      typed_get(key, Float, default: default, context: context)
+    end
+
+    def get_bool(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
+      typed_get(key, :bool, default: default, context: context)
+    end
+
+    def get_string_list(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
+      typed_get(key, :string_list, default: default, context: context)
+    end
+
+    def get_duration(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
+      typed_get(key, :duration, default: default, context: context)
+    end
+
+    def get_json(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
+      typed_get(key, :json, default: default, context: context)
+    end
+
+    def enabled?(feature_name, jit_context = NO_DEFAULT_PROVIDED)
+      value = get(feature_name, false, jit_context)
+      value == true || value == 'true'
+    end
+
+    def defined?(key)
+      !@store.get(key).nil?
+    end
+
+    def keys
+      @store.keys
+    end
+
+    # ---- Context binding ----------------------------------------------
+
+    def in_context(properties)
+      bound = Quonfig::BoundClient.new(self, properties)
+      block_given? ? yield(bound) : bound
+    end
+
+    def with_context(properties, &block)
+      if block_given?
+        in_context(properties, &block)
+      else
+        Quonfig::BoundClient.new(self, properties)
+      end
+    end
+
+    # ---- Filters & helpers --------------------------------------------
+
+    def semantic_logger_filter(config_key:)
+      @semantic_logger_filters[config_key] ||=
+        Quonfig::SemanticLoggerFilter.new(self, config_key: config_key)
+    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.
+    end
+
+    def fork
+      self.class.new(@options.for_fork)
+    end
+
+    def inspect
+      "#<Quonfig::Client:#{object_id} environment=#{@options.environment.inspect}>"
+    end
+
+    private
+
+    def build_store
+      if @options.datadir
+        Quonfig::Datadir.load_store(@options.datadir, @options.environment)
+      else
+        Quonfig::ConfigStore.new
+      end
+    end
+
+    def build_context(jit_context)
+      jit = jit_context == NO_DEFAULT_PROVIDED ? nil : normalize_context(jit_context)
+      merge_contexts(@global_context, jit)
+    end
+
+    def normalize_context(ctx)
+      return {} if ctx.nil?
+      return ctx if ctx.is_a?(Hash)
+
+      raise ArgumentError, "Quonfig context must be a Hash, got #{ctx.class}"
+    end
+
+    # One-level-deep merge per named context (mirrors sdk-node's mergeContexts):
+    # later values override earlier within the same named context; keys unique
+    # to each side are preserved.
+    def merge_contexts(left, right)
+      return right || {} if left.nil? || left.empty?
+      return left if right.nil? || right.empty?
+
+      merged = {}
+      left.each  { |name, ctx| merged[name] = ctx.is_a?(Hash) ? ctx.dup : ctx }
+      right.each do |name, ctx|
+        if merged[name].is_a?(Hash) && ctx.is_a?(Hash)
+          merged[name] = merged[name].merge(ctx)
+        else
+          merged[name] = ctx.is_a?(Hash) ? ctx.dup : ctx
+        end
+      end
+      merged
+    end
+
+    def handle_missing(key, default)
+      return default if default != NO_DEFAULT_PROVIDED
+
+      if @options.on_no_default == Quonfig::Options::ON_NO_DEFAULT::RAISE
+        raise Quonfig::Errors::MissingDefaultError, key
+      end
+
+      nil
+    end
+
+    def typed_get(key, expected_type, default:, context:)
+      jit = context == NO_DEFAULT_PROVIDED ? NO_DEFAULT_PROVIDED : context
+      value = get(key, default, jit)
+
+      # Missing path: resolver returned the caller's default (or nil under
+      # on_no_default=:return_nil) — skip type coercion.
+      return value if default != NO_DEFAULT_PROVIDED && value.equal?(default)
+      return nil if value.nil?
+
+      coerce_and_check(key, value, expected_type)
+    end
+
+    def coerce_and_check(key, value, expected_type)
+      case expected_type
+      when :bool
+        unless value == true || value == false
+          raise Quonfig::Errors::TypeMismatchError.new(key, 'Boolean', value)
+        end
+        value
+      when :string_list
+        arr = value.is_a?(Array) ? value : nil
+        unless arr && arr.all? { |v| v.is_a?(String) }
+          raise Quonfig::Errors::TypeMismatchError.new(key, 'Array<String>', value)
+        end
+        arr
+      when :duration
+        return value.to_i if value.is_a?(Numeric)
+        if value.is_a?(String)
+          return (Quonfig::Duration.parse(value) * 1000).to_i
+        end
+        raise Quonfig::Errors::TypeMismatchError.new(key, 'ISO-8601 Duration', value)
+      when :json
+        # JSON values are returned as-is (Hash, Array, or scalar from the wire).
+        value
+      when Class
+        unless value.is_a?(expected_type)
+          raise Quonfig::Errors::TypeMismatchError.new(key, "expected #{expected_type}", value)
+        end
+        value
+      else
+        value
+      end
+    end
+  end
+end

data/lib/quonfig/config_envelope.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Quonfig
+  ConfigEnvelope = Struct.new(:configs, :meta, keyword_init: true)
+end

data/lib/quonfig/config_loader.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Quonfig
+  class ConfigLoader
+    LOG = Quonfig::InternalLogger.new(self)
+
+    CONFIGS_PATH = '/api/v2/configs'
+
+    attr_reader :etag
+
+    def initialize(base_client)
+      @base_client = base_client
+      @options = base_client.options
+      @api_config = Concurrent::Map.new
+      @etag = nil
+    end
+
+    # Fetch configs from /api/v2/configs with ETag / If-None-Match caching.
+    #
+    # Returns one of:
+    #   :updated       — 200 response; @api_config and @etag replaced
+    #   :not_modified  — 304 response; cache still valid
+    #   :failed        — every configured source failed
+    def fetch!
+      Array(@options.config_api_urls).each do |api_url|
+        result = fetch_from(api_url)
+        return result if result != :failed
+      end
+      :failed
+    end
+
+    def calc_config
+      rtn = {}
+      @api_config.each_key do |k|
+        rtn[k] = @api_config[k]
+      end
+      rtn
+    end
+
+    def set(config, source)
+      @api_config[config.key] = { source: source, config: config }
+    end
+
+    def rm(key)
+      @api_config.delete(key)
+    end
+
+    private
+
+    def fetch_from(source)
+      conn = Quonfig::HttpConnection.new(source, @options.sdk_key)
+      headers = {}
+      headers['If-None-Match'] = @etag if @etag
+      response = conn.get(CONFIGS_PATH, headers)
+
+      case response.status
+      when 200
+        new_etag = response.headers['ETag'] || response.headers['etag']
+        envelope = parse_envelope(response.body)
+        replace_api_config(envelope, source)
+        @etag = new_etag
+        :updated
+      when 304
+        LOG.debug "Configs not modified (304) from #{source}"
+        :not_modified
+      else
+        LOG.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}"
+      :failed
+    rescue StandardError => e
+      LOG.warn "Unexpected error fetching configs from #{source}: #{e.message}"
+      :failed
+    end
+
+    def parse_envelope(body)
+      data = body.is_a?(String) ? JSON.parse(body) : body
+      Quonfig::ConfigEnvelope.new(
+        configs: data['configs'] || [],
+        meta: data['meta'] || {}
+      )
+    end
+
+    def replace_api_config(envelope, source)
+      next_map = Concurrent::Map.new
+      envelope.configs.each do |cfg|
+        key = config_key(cfg)
+        next if key.nil?
+        next_map[key] = { source: source, config: cfg }
+      end
+      @api_config = next_map
+    end
+
+    def config_key(cfg)
+      return cfg['key'] || cfg[:key] if cfg.is_a?(Hash)
+      cfg.respond_to?(:key) ? cfg.key : nil
+    end
+  end
+end

data/lib/quonfig/config_store.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Quonfig
+  # In-memory store of configs keyed by config key.
+  #
+  # Mirrors sdk-node's ConfigStore (src/store.ts). Integration tests and the
+  # new Resolver/Evaluator trio construct this directly, independent of any
+  # Client/ConfigLoader plumbing.
+  class ConfigStore
+    def initialize(initial_configs = nil)
+      @lock = Concurrent::ReadWriteLock.new
+      @configs = Concurrent::Map.new
+      return unless initial_configs
+
+      initial_configs.each { |k, v| @configs[k] = v }
+    end
+
+    def get(key)
+      @configs[key]
+    end
+
+    def set(key, config)
+      @lock.with_write_lock { @configs[key] = config }
+    end
+
+    def clear
+      @lock.with_write_lock do
+        @configs.keys.each { |k| @configs.delete(k) }
+      end
+    end
+
+    def keys
+      @configs.keys
+    end
+
+    def all_configs
+      h = {}
+      @configs.each_pair { |k, v| h[k] = v }
+      h
+    end
+  end
+end

data/lib/quonfig/context.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Quonfig
+  # Quonfig context: a two-level Hash (named-context → property → value) wrapped
+  # for evaluator consumption. The Evaluator accepts either a plain Hash or a
+  # Quonfig::Context — this class exists mostly to flatten lookups (`get`)
+  # into the dotted "context-name.property" form criterion rules use.
+  class Context
+    BLANK_CONTEXT_NAME = ''
+
+    class NamedContext
+      attr_reader :name
+
+      def initialize(name, hash)
+        @name = name.to_s
+        @hash = hash.transform_keys(&:to_s)
+      end
+
+      def to_h
+        @hash
+      end
+
+      def key
+        "#{@name}:#{@hash['key']}"
+      end
+
+      def merge!(other)
+        other.each { |k, v| @hash[k.to_s] = v }
+        self
+      end
+    end
+
+    attr_reader :contexts
+
+    def initialize(hash = {})
+      @contexts = {}
+      @flattened = {}
+
+      raise ArgumentError, 'must be a Hash' unless hash.is_a?(Hash)
+
+      hash.each do |name, values|
+        unless values.is_a?(Hash)
+          # Legacy shorthand — pre-named-contexts callers passed a flat Hash.
+          values = { name => values }
+          name = BLANK_CONTEXT_NAME
+        end
+
+        @contexts[name.to_s] = NamedContext.new(name, values)
+        values.each do |key, value|
+          @flattened[name.to_s + '.' + key.to_s] = value
+        end
+      end
+    end
+
+    def blank?
+      @contexts.empty?
+    end
+
+    def set(name, hash)
+      @contexts[name.to_s] = NamedContext.new(name, hash)
+      hash.each do |key, value|
+        @flattened[name.to_s + '.' + key.to_s] = value
+      end
+    end
+
+    def get(property_key, scope: nil)
+      property_key = BLANK_CONTEXT_NAME + '.' + property_key unless property_key.include?('.')
+      @flattened[property_key]
+    end
+
+    def to_h
+      @contexts.transform_values(&:to_h)
+    end
+
+    def to_s
+      "#<Quonfig::Context:#{object_id} #{to_h}>"
+    end
+
+    def clear
+      @contexts = {}
+      @flattened = {}
+    end
+
+    def context(name)
+      @contexts[name.to_s] || NamedContext.new(name, {})
+    end
+
+    def grouped_key
+      @contexts.map { |_, ctx| ctx.key }.sort.join('|')
+    end
+
+    include Comparable
+    def <=>(other)
+      if other.is_a?(Quonfig::Context)
+        to_h <=> other.to_h
+      else
+        super
+      end
+    end
+  end
+end