confeature 0.0.0 → 0.1.0

data/lib/confeature/internal/hashing.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: MIT
+
+require "digest"
+
+module Confeature
+  module Internal
+    # ConfigCat evaluation hashes — SHA-1 (unsalted %) + SHA-256 (salted
+    # sensitive). Ported field-for-field from the spec-117 TS reference
+    # (`packages/sdk-shared/src/hash.ts`) and the spec-118 Python port
+    # (`apps/sdk-python/src/confeature_client/hash.py`). The flag evaluator
+    # needs two synchronous hashes:
+    #
+    #   - **SHA-1, UNSALTED** for percentage bucketing —
+    #     `Digest::SHA1.hexdigest(key + attr_value)[0, 7].to_i(16) % 100`.
+    #   - **SHA-256, SALTED** for sensitive comparators —
+    #     `sha256(utf8(value) + utf8(config_salt) + utf8(context_salt))`.
+    #
+    # Unlike the TS reference (which vendors a pure-JS implementation because
+    # `crypto.subtle` is async on every runtime), Ruby's stdlib `Digest` is
+    # synchronous and present everywhere, so we use it directly. The bytes
+    # hashed are identical to the TS / Python implementations — UTF-8-encoded
+    # text for the text paths, raw byte slices for the startsWith/endsWith
+    # slice scheme — so every bucket / hash comes out byte-identical across the
+    # federation (the parity corpus requires this).
+    # Named `Hashing` (not `Hash`) to avoid shadowing Ruby's core `::Hash`
+    # class for any unqualified `Hash` reference elsewhere in
+    # `Confeature::Internal` (e.g. `body.is_a?(Hash)` in `config_fetcher.rb`).
+    module Hashing
+      module_function
+
+      # Lowercase-hex SHA-1 of raw bytes (mirrors `hash.ts::sha1`).
+      def sha1_hex(data)
+        Digest::SHA1.hexdigest(data)
+      end
+
+      # Lowercase-hex SHA-256 of raw bytes (mirrors `hash.ts::sha256Bytes`).
+      def sha256_hex(data)
+        Digest::SHA256.hexdigest(data)
+      end
+
+      # Hash a user-attribute value for a **sensitive** comparator. Mirrors
+      # `hash.ts::hashComparisonValue` (common-js `hashComparisonValue`):
+      #
+      #     sha256( utf8(value) + utf8(config_json_salt) + utf8(context_salt) )
+      #
+      # concatenated with no separators, output as lowercase hex.
+      #
+      # @param value [String] attribute value as text (after conversion).
+      # @param config_json_salt [String] top-level config salt (`config["p"]["s"]`).
+      # @param context_salt [String] per-evaluation discriminator — the setting
+      #   key for a user condition, the segment name for a segment condition.
+      def hash_comparison_value(value, config_json_salt, context_salt)
+        sha256_hex(b("#{value}#{config_json_salt}#{context_salt}"))
+      end
+
+      # Hash a UTF-8 byte slice for a sensitive startsWith/endsWith comparator.
+      # Mirrors `comparators.ts::hashComparisonValueSlice`:
+      #
+      #     sha256( slice_bytes ++ utf8(config_salt) ++ utf8(context_salt) )
+      #
+      # The slice is **raw bytes** — a byte-boundary cut of the attribute, which
+      # may land mid-codepoint — so the hash runs over the concatenated byte
+      # sequence (re-encoding a binary string as UTF-8 would corrupt multibyte
+      # attributes, the `testmatrix_unicode` `*Hashed` rows). `slice_utf8` is an
+      # ASCII-8BIT (binary) string.
+      def hash_comparison_value_slice(slice_utf8, config_json_salt, context_salt)
+        sha256_hex(slice_utf8 + b(config_json_salt) + b(context_salt))
+      end
+
+      # Compute a ConfigCat percentage bucket in `[0, 99]` for
+      # `key + attr_value`. Mirrors `hash.ts::percentageBucket`:
+      #
+      #     sha1(key + attr_value).hexdigest[0, 7].to_i(16) % 100
+      #
+      # SHA-1, **unsalted**. 7 hex chars = 28 bits, well within a safe integer.
+      def percentage_bucket(key, attr_value)
+        sha1_hex(b("#{key}#{attr_value}"))[0, 7].to_i(16) % 100
+      end
+
+      # Force a string to its UTF-8 bytes as a binary blob so `Digest` hashes
+      # the exact byte sequence (and concatenation with binary slices works).
+      def b(str)
+        str.encode(Encoding::UTF_8).b
+      end
+    end
+  end
+end

data/lib/confeature/internal/override_eval.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: MIT
+
+require_relative "../flag_overrides"
+require_relative "evaluator"
+
+module Confeature
+  module Internal
+    # Synchronous override evaluation — Ruby port of `EvaluateSync`.
+    #
+    # Byte-identical 7-branch decision tree from
+    # `apps/sdk-go/internal/overrideeval/eval.go` (Go) and
+    # `packages/sdk-shared/src/override-eval.ts` (TS canonical). The
+    # Python port lives at
+    # `apps/sdk-python/src/confeature_client/override_eval.py`. The
+    # parity corpus is the canonical gate.
+    #
+    # The helper is intentionally pure: no logger access, no SDK-key
+    # access, no I/O. Pure data in → tuple `[found, value]` out.
+    #
+    # Returns:
+    #   - `[false, nil]` when overrides are absent, behaviour is
+    #     non-LocalOnly, or no synchronous data source is available
+    #     (Branches 1-3: caller falls through to the cache).
+    #   - `[true, <value>]` when overrides + LocalOnly + key match
+    #     (Branch 7 — typed override value); also
+    #     `[true, default_value]` for the LocalOnly fallback branches
+    #     4-6 (key absent / empty slot / TYPE_MISMATCH).
+    module OverrideEval
+      module_function
+
+      def evaluate_sync(flag_overrides, key, default_value)
+        # Branch 1: no overrides configured → caller falls through.
+        return [false, nil] if flag_overrides.nil?
+
+        # Branch 2: non-LocalOnly behaviours short-circuit (spec 031 §R8).
+        return [false, nil] if flag_overrides.behaviour != OverrideBehaviour::LOCAL_ONLY
+
+        # Branch 3: no synchronous data source available → fall through.
+        data_source = flag_overrides.data_source
+        return [false, nil] if data_source.nil?
+        return [false, nil] unless data_source.respond_to?(:get_overrides_sync)
+
+        overrides_map = data_source.get_overrides_sync
+        return [false, nil] if overrides_map.nil?
+
+        # From here we are committed to the LocalOnly contract: NEVER
+        # fall through to the cache — return either the typed override
+        # or the supplied default.
+
+        # Branch 4: key absent → return default.
+        raw = overrides_map[key]
+        return [true, default_value] if raw.nil?
+
+        # Branch 5: override slot empty → return default.
+        candidate = raw.picked
+        return [true, default_value] if candidate.nil?
+
+        # Branch 6: TYPE_MISMATCH — primitive types diverge → return default.
+        # A `nil` default_value intentionally bypasses the check (matches
+        # configcat-js's `defaultValue !== null` ternary). In Ruby
+        # `true.class` and `false.class` differ (TrueClass / FalseClass)
+        # — treat both as the same "boolean" bucket so a `true`
+        # override matched against a `false` default is NOT a type
+        # mismatch.
+        if !default_value.nil? && !boolean_kind_match?(candidate, default_value) &&
+           candidate.class != default_value.class
+          return [true, default_value]
+        end
+
+        # Branch 7: happy path — typed override value.
+        [true, candidate]
+      end
+
+      def boolean_kind_match?(candidate, default_value)
+        boolean?(candidate) && boolean?(default_value)
+      end
+
+      def boolean?(value)
+        value.is_a?(TrueClass) || value.is_a?(FalseClass)
+      end
+
+      # Full-config override resolution — Ruby port of
+      # `evaluateFullConfigOverrideSync` (spec 135 / #431).
+      #
+      # When the override source is a `ConfigOverrideDataSource`, resolve
+      # `key` through the real Ruby evaluator so targeting rules /
+      # segments / prerequisites / percentage options apply offline — the
+      # rule-bearing sibling of `evaluate_sync`'s flat lookup.
+      #
+      # Returns:
+      #   - `[true, <value>]` when overrides + LocalOnly + a
+      #     `ConfigOverrideDataSource` apply (LocalOnly: never fall
+      #     through to the cache — the evaluator already returns
+      #     `default_value` for any non-clean resolution, so this
+      #     preserves the contract);
+      #   - `[false, nil]` when overrides are absent, behaviour is
+      #     non-LocalOnly, or the source is NOT a full-config source
+      #     (caller falls through to the flat-map helper / normal eval).
+      #
+      # INV-4: the evaluator receives the FULL config Hash (`{ p, f, s }`)
+      # — salt (`p.s`) + segments (`s`), never just `f` (the spec-129
+      # dropped-salt regression class).
+      def evaluate_full_config_override_sync(flag_overrides, key, default_value, user)
+        return [false, nil] if flag_overrides.nil?
+        return [false, nil] if flag_overrides.behaviour != OverrideBehaviour::LOCAL_ONLY
+
+        data_source = flag_overrides.data_source
+        return [false, nil] unless data_source.is_a?(ConfigOverrideDataSource)
+
+        # Pass the FULL config Hash (salt + segments + f), never just `f`
+        # (INV-4).
+        result = Evaluator.evaluate(data_source.config, key, default_value, user)
+        [true, result.value]
+      end
+
+      # Details-returning sibling of `evaluate_full_config_override_sync`
+      # (spec 152 / #475, US2 — Ruby port of Python's
+      # `evaluate_full_config_override_details_sync`).
+      #
+      # Resolves `key` through the real evaluator and returns the full
+      # `EvaluationResult` (value + served `variation_id` + matched
+      # rule / option) so the PUBLIC `get_value_details` surfaces the
+      # override's identity. Closes the #395 gap class: the snapshot's
+      # LocalOnly details branch previously routed a
+      # `ConfigOverrideDataSource` through the value-only flat-map helper
+      # (which cannot read rule-bearing settings and never carries a
+      # `variation_id`).
+      #
+      # Returns:
+      #   - `[true, <EvaluationResult>]` when overrides + LocalOnly + a
+      #     `ConfigOverrideDataSource` apply;
+      #   - `[false, nil]` when overrides are absent, behaviour is
+      #     non-LocalOnly, or the source is NOT a full-config source
+      #     (caller falls through to the flat-map details branch —
+      #     unchanged value-only override semantics).
+      #
+      # INV-4: the evaluator receives the FULL config Hash (`{ p, f, s }`)
+      # — salt (`p.s`) + segments (`s`), never just `f`.
+      def evaluate_full_config_override_details_sync(flag_overrides, key, default_value, user)
+        return [false, nil] if flag_overrides.nil?
+        return [false, nil] if flag_overrides.behaviour != OverrideBehaviour::LOCAL_ONLY
+
+        data_source = flag_overrides.data_source
+        return [false, nil] unless data_source.is_a?(ConfigOverrideDataSource)
+
+        # Pass the FULL config Hash (salt + segments + f), never just `f`
+        # (INV-4).
+        result = Evaluator.evaluate(data_source.config, key, default_value, user)
+        [true, result]
+      end
+
+      # Shared override router — Ruby port of `evaluateOverride`
+      # (spec 135 / #431).
+      #
+      # Dispatches between the flat-map path and the full-config path so
+      # the `get_value` call site changes minimally: a
+      # `ConfigOverrideDataSource` routes through the real evaluator;
+      # every other source (map / custom) keeps the existing
+      # byte-identical flat-map resolution.
+      #
+      # Returns `[found, value]` — `[false, nil]` when no override applies
+      # (the caller then falls through to the normal cache-driven eval).
+      # Preserves the LocalOnly no-fall-through contract on both paths.
+      def evaluate(flag_overrides, key, default_value, user)
+        # Full-config source → ALWAYS resolve through the evaluator; NEVER
+        # fall through to the flat-map path (which would mis-read
+        # rule-bearing settings as value-only). Dispatch on the source
+        # TYPE, not the resolved value, so a full-config source whose
+        # evaluator returns the default still stays on the rule path.
+        if !flag_overrides.nil? &&
+           flag_overrides.behaviour == OverrideBehaviour::LOCAL_ONLY &&
+           flag_overrides.data_source.is_a?(ConfigOverrideDataSource)
+          return evaluate_full_config_override_sync(flag_overrides, key, default_value, user)
+        end
+
+        # Every other source (map / custom) keeps the byte-identical
+        # flat-map path.
+        evaluate_sync(flag_overrides, key, default_value)
+      end
+    end
+  end
+end

data/lib/confeature/internal/poll_service.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: MIT
+
+require_relative "../polling_mode"
+
+module Confeature
+  module Internal
+    # Polling strategies: AutoPoll (daemon thread), LazyLoad (on-demand
+    # staleness), ManualPoll (caller-driven).
+    #
+    # Lifecycle:
+    #   - constructor accepts a `fetch_callback` (no args, returns
+    #     ConfigFetcher::FetchResult) bound to the client's
+    #     ConfigFetcher.
+    #   - `start(callback)` is idempotent. AutoPoll spawns its daemon
+    #     thread here. LazyLoad / ManualPoll record the callback but
+    #     spawn nothing.
+    #   - `force_refresh` invokes the callback synchronously and
+    #     returns a `RefreshResult`.
+    #   - `stop(timeout: 5.0)` signals the thread and joins (no-op for
+    #     non-AutoPoll modes).
+    #
+    # AutoPoll uses `Thread.new` + `Mutex` + `ConditionVariable` for
+    # cancel signalling. Threads are daemon so process shutdown never
+    # hangs on a poll-thread join.
+    module PollService
+      RefreshResult = Struct.new(:success, :error, keyword_init: true) do
+        def self.from_fetch(fetch_result)
+          if %i[fetched not_modified].include?(fetch_result.status)
+            new(success: true)
+          else
+            new(success: false, error: fetch_result.error || "FETCH_FAILED")
+          end
+        end
+      end
+
+      # Abstract base — subclasses provide the per-mode behaviour.
+      class Base
+        def start(_callback)
+          raise NotImplementedError
+        end
+
+        def stop(timeout: 5.0)
+          raise NotImplementedError
+        end
+
+        def force_refresh
+          raise NotImplementedError
+        end
+
+        # Hook for LazyLoad's on-demand staleness-driven fetch.
+        # AutoPoll + ManualPoll return immediately.
+        def maybe_fetch_for_get_value
+          nil
+        end
+      end
+
+      class AutoPollService < Base
+        def initialize(options)
+          super()
+          @options = options
+          @callback = nil
+          @started = false
+          @mutex = Mutex.new
+          @stop_mutex = Mutex.new
+          @stop_cond = ConditionVariable.new
+          @stopped = false
+          @thread = nil
+        end
+
+        def start(callback)
+          @mutex.synchronize do
+            return if @started
+
+            @callback = callback
+            @started = true
+          end
+
+          # Eager initial fetch so first get_value lands on real config.
+          safe_invoke(@callback)
+
+          @thread = Thread.new { run_loop }
+          @thread.name = "confeature-autopoll" if @thread.respond_to?(:name=)
+          @thread.report_on_exception = false if @thread.respond_to?(:report_on_exception=)
+        end
+
+        def stop(timeout: 5.0)
+          @stop_mutex.synchronize do
+            @stopped = true
+            @stop_cond.broadcast
+          end
+          thread = @thread
+          @thread = nil
+          thread&.join(timeout)
+          nil
+        end
+
+        def force_refresh
+          cb = @callback
+          return RefreshResult.new(success: false, error: "NOT_STARTED") if cb.nil?
+
+          result = safe_invoke(cb)
+          return RefreshResult.new(success: false, error: "CALLBACK_RAISED") if result.nil?
+
+          RefreshResult.from_fetch(result)
+        end
+
+        private
+
+        def run_loop
+          interval = @options.poll_interval_seconds
+          loop do
+            @stop_mutex.synchronize do
+              return if @stopped
+
+              @stop_cond.wait(@stop_mutex, interval)
+              return if @stopped
+            end
+            cb = @callback
+            return if cb.nil?
+
+            safe_invoke(cb)
+          end
+        end
+
+        # Returns the callback's result, or nil if the callback raised.
+        # The shipped `ConfigFetcher.fetch` is fail-closed; this guard
+        # exists so a misbehaving custom callback can't crash the
+        # daemon thread or the force_refresh path.
+        def safe_invoke(cb)
+          cb.call
+        rescue StandardError
+          nil
+        end
+      end
+
+      class LazyLoadService < Base
+        def initialize(options)
+          super()
+          @options = options
+          @callback = nil
+          @last_fetched_at = 0.0
+          @mutex = Mutex.new
+        end
+
+        def start(callback)
+          @mutex.synchronize { @callback = callback }
+        end
+
+        def stop(timeout: 5.0) # rubocop:disable Lint/UnusedMethodArgument
+          nil
+        end
+
+        def force_refresh
+          cb = @callback
+          return RefreshResult.new(success: false, error: "NOT_STARTED") if cb.nil?
+
+          result = RefreshResult.from_fetch(cb.call)
+          @mutex.synchronize { @last_fetched_at = Time.now.to_f } if result.success
+          result
+        end
+
+        def maybe_fetch_for_get_value
+          cb = @callback
+          return nil if cb.nil?
+
+          now = Time.now.to_f
+          stale = (now - @last_fetched_at) >= @options.cache_refresh_interval_seconds
+          return nil unless stale
+
+          begin
+            cb.call
+            @mutex.synchronize { @last_fetched_at = Time.now.to_f }
+          rescue StandardError
+            # Swallow — fetch errors are logged inside ConfigFetcher.
+          end
+          nil
+        end
+      end
+
+      class ManualPollService < Base
+        def initialize
+          super
+          @callback = nil
+        end
+
+        def start(callback)
+          @callback = callback
+        end
+
+        def stop(timeout: 5.0) # rubocop:disable Lint/UnusedMethodArgument
+          nil
+        end
+
+        def force_refresh
+          cb = @callback
+          return RefreshResult.new(success: false, error: "NOT_STARTED") if cb.nil?
+
+          RefreshResult.from_fetch(cb.call)
+        end
+      end
+
+      # Build the service matching the supplied PollingMode value.
+      def self.build(mode)
+        case mode
+        when PollingMode::AutoPoll then AutoPollService.new(mode)
+        when PollingMode::LazyLoad then LazyLoadService.new(mode)
+        when PollingMode::ManualPoll then ManualPollService.new
+        else
+          raise ArgumentError,
+                "Unsupported polling mode: #{mode.inspect}. " \
+                "Use PollingMode.auto_poll, .lazy_load, or .manual_poll."
+        end
+      end
+    end
+  end
+end

data/lib/confeature/internal/prerequisites.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: MIT
+
+module Confeature
+  module Internal
+    # Prerequisite-flag condition resolution + circular-dependency detection.
+    # Ported from the spec-117 TS reference
+    # (`packages/sdk-shared/src/prerequisites.ts`) and the spec-118 Python port,
+    # itself from common-js `RolloutEvaluator.evaluatePrerequisiteFlagCondition`.
+    #
+    # A prerequisite condition (`{ "f" => key, "c" => comparator, "v" => env }`)
+    # is resolved by **re-evaluating the prerequisite flag** in a child context
+    # (same config / user, SHARED `visited_flags` list), then comparing its
+    # resolved value to the expected `v` via the comparator (`Equals` /
+    # `NotEquals`). Both the resolved value and `v` are read through the
+    # prerequisite flag's own declared `SettingType`.
+    #
+    # **Cycle detection** uses the shared `visited_flags` list: push the CURRENT
+    # key, check whether the prerequisite key is already on the list BEFORE
+    # recursing — if so, push the prerequisite key too and raise
+    # `CircularDependencyError`. The outer `evaluate` rescue-all turns that into
+    # a fail-closed fallback + error, so a cycle is **bounded** (the key set is
+    # finite; the second visit raises) — never a hang, never a `SystemStackError`
+    # escape (FR-007, SC-004). On the non-cycle path the current key is popped
+    # after the child evaluation returns, restoring the list for siblings.
+    module Prerequisites
+      PREREQUISITE_EQUALS = 0
+      PREREQUISITE_NOT_EQUALS = 1
+
+      # Raised on a detected prerequisite cycle (caught by `evaluate`'s frame).
+      # `cycle` carries the `key -> … -> key` chain so the trace logger can emit
+      # ConfigCat's distinct ERROR 1002 line (`[<cycle>]`) without re-parsing the
+      # message (mirrors the .NET / Rust ports).
+      class CircularDependencyError < StandardError
+        attr_reader :cycle
+
+        def initialize(cycle)
+          @cycle = cycle
+          super("Circular dependency detected between the following depending flags: #{cycle}.")
+        end
+      end
+
+      # A missing / invalid prerequisite flag — a fatal config error
+      # (fail-closed, caught by the evaluator's rescue-all).
+      class PrerequisiteReferenceError < StandardError; end
+
+      module_function
+
+      # Resolve one prerequisite-flag condition. The setting re-evaluator +
+      # value selector are injected so this module has no back-reference to the
+      # evaluator. Returns the comparison result (`true` / `false`). Raises
+      # `CircularDependencyError` on a detected cycle or
+      # `PrerequisiteReferenceError` on a missing prerequisite flag.
+      def evaluate_prerequisite_flag_condition(
+        condition, current_key, visited_flags, prereq_type, evaluate_prereq_flag, select_value
+      )
+        prereq_key = condition["f"]
+        raise PrerequisiteReferenceError, "Prerequisite flag key is missing or invalid." unless prereq_key.is_a?(String)
+
+        declared_type = prereq_type.call(prereq_key)
+        raise PrerequisiteReferenceError, "Prerequisite flag is missing or invalid." if declared_type.nil?
+
+        # The expected comparison value `v`, read through the prereq flag's type.
+        comparison_value = select_value.call(condition["v"], declared_type)
+
+        # Cycle detection: push current key, detect a revisit BEFORE recursing.
+        visited_flags.push(current_key)
+        if visited_flags.include?(prereq_key)
+          visited_flags.push(prereq_key)
+          raise CircularDependencyError, visited_flags.join(" -> ")
+        end
+
+        resolved_envelope = evaluate_prereq_flag.call(prereq_key)
+        # Restore the list for sibling prerequisites (common-js pops here).
+        visited_flags.pop
+
+        resolved_value = select_value.call(resolved_envelope, declared_type)
+
+        case condition["c"]
+        when PREREQUISITE_EQUALS then resolved_value == comparison_value
+        when PREREQUISITE_NOT_EQUALS then resolved_value != comparison_value
+        else raise PrerequisiteReferenceError, "Comparison operator is missing or invalid."
+        end
+      end
+    end
+  end
+end