confeature 0.0.0 → 0.1.0

data/lib/confeature/internal/sdk_key.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: MIT
+
+require "base64"
+require "digest"
+
+module Confeature
+  module Internal
+    # SDK-key format helpers + cache-key derivation.
+    #
+    # SECURITY (Constitution security clause + spec 037 FR-008): SDK
+    # keys are secrets. They MUST NEVER appear verbatim in any log
+    # line. Every log site routes through `redact` first.
+    #
+    # The cache-key algorithm mirrors `packages/sdk-shared/src/sdk-key.ts`
+    # (SHA-256 → base64url → first 32 chars). Cross-language fixture
+    # verification lives in `spec/cache_key_fixtures_spec.rb`.
+    module SdkKey
+      # Wire formats of a valid Confeature SDK key — both are accepted
+      # (#802):
+      #
+      #   - `configcat-sdk-1/<22 url-safe chars>/<22 url-safe chars>` —
+      #     minted today; ConfigCat's own shape, so the stock `configcat`
+      #     gem accepts the key too.
+      #   - `confeature-sdk-1-<32 url-safe chars>-<32 url-safe chars>` —
+      #     minted before #802; still served until the key is rotated.
+      #
+      # Mirrors `CONFEATURE_SDK_KEY_PATTERN` in
+      # `packages/sdk-shared/src/sdk-key.ts`. The shared accept/reject
+      # cases live in
+      # `packages/test-fixtures-sdk-parity/fixtures/sdk-key-shapes.json`.
+      CONFEATURE_SDK_KEY_PATTERN = %r{
+        \A
+        (?:
+          configcat-sdk-1/[A-Za-z0-9_-]{22}/[A-Za-z0-9_-]{22}
+          |
+          confeature-sdk-1-[A-Za-z0-9_-]{32}-[A-Za-z0-9_-]{32}
+        )
+        \z
+      }x
+
+      # Envelope prefix for derived cache keys. Identical across every
+      # Confeature SDK; mirrors the TS implementation's constant.
+      CACHE_KEY_PREFIX = "confeature:cache:v1:"
+
+      # Return true iff `sdk_key` matches either Confeature SDK-key format
+      # (the ConfigCat-shaped `configcat-sdk-1/...` key or the legacy
+      # `confeature-sdk-1-...` key).
+      #
+      # A `false` result does NOT cause the SDK to raise; it triggers an
+      # `INVALID_SDK_KEY` log line (which, per the security clause,
+      # includes only the redacted form).
+      def self.valid_confeature_key_format?(sdk_key)
+        return false unless sdk_key.is_a?(String)
+
+        # Matched on the raw bytes: a key in a broken or non-ASCII-
+        # compatible encoding is simply not well-shaped, never an
+        # `ArgumentError` / `Encoding::CompatibilityError` (#803).
+        CONFEATURE_SDK_KEY_PATTERN.match?(sdk_key.b)
+      end
+
+      # Return a privacy-preserving rendering of `sdk_key` for logs.
+      #
+      # Strategy: keep ~10% of the key visible at each end (minimum 4
+      # chars), mask the middle. For short / unusual keys (< 16 chars)
+      # and nil, fall back to a full mask. NEVER returns the raw key.
+      #
+      # The `/` separators of a ConfigCat-shaped key are plain characters
+      # here: for a 61-char `configcat-sdk-1/<22>/<22>` key the head is
+      # `config` (no secret) and the tail is the last 6 secret chars —
+      # fewer than the 8 shown for a legacy 83-char key.
+      #
+      # Mirrors `redactSdkKey` from packages/sdk-shared/src/sdk-key.ts.
+      def self.redact(sdk_key)
+        return "[redacted]" if sdk_key.nil? || !sdk_key.is_a?(String) || sdk_key.empty?
+
+        key = printable(sdk_key)
+        return "[redacted]" if key.nil? || key.length < 16
+
+        visible = [4, (key.length / 10.0).floor].max
+        head = key[0, visible]
+        tail = key[-visible, visible]
+        "#{head}…[redacted]…#{tail}"
+      end
+
+      # `sdk_key` as valid UTF-8 (bad bytes replaced), so interpolating
+      # it next to the UTF-8 "…" never raises an encoding error (#803).
+      # A valid UTF-8 key is returned unchanged. nil when no conversion
+      # exists.
+      def self.printable(sdk_key)
+        return sdk_key.scrub if sdk_key.encoding == Encoding::UTF_8
+
+        sdk_key.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+      rescue EncodingError
+        nil
+      end
+      private_class_method :printable
+
+      # Derive a stable, opaque cache key from an SDK key.
+      #
+      # Format: `confeature:cache:v1:<base64url(sha256(sdk_key))[0, 32]>`.
+      #
+      # Output is byte-identical to the TS workspace's async
+      # `deriveCacheKey` (Web Crypto's `subtle.digest("SHA-256")`).
+      # The cross-language fixture at
+      # `packages/test-fixtures-sdk-parity/fixtures/cache-key-fixtures.json`
+      # pins ≥ 5 (sdkKey, expectedCacheKey) pairs and the Ruby unit test
+      # asserts string equality for every entry.
+      #
+      # SECURITY: the SDK key is HASHED, never stored raw. Even an
+      # attacker with filesystem access to the cache directory cannot
+      # read the SDK key from a written cache file's name.
+      def self.derive_cache_key(sdk_key)
+        digest = Digest::SHA256.digest(sdk_key.to_s.b)
+        b64 = Base64.urlsafe_encode64(digest, padding: false)
+        "#{CACHE_KEY_PREFIX}#{b64[0, 32]}"
+      end
+    end
+  end
+end

data/lib/confeature/internal/segments.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: MIT
+
+require_relative "comparators"
+
+module Confeature
+  module Internal
+    # Segment-condition resolution (v6 + legacy v5). Ported from the spec-117 TS
+    # reference (`packages/sdk-shared/src/segments.ts`) and the spec-118 Python
+    # port, itself from common-js `RolloutEvaluator.evaluateSegmentCondition`.
+    #
+    # A segment condition (`{ "s" => index, "c" => comparator }`) references a
+    # segment by index into the config's top-level `s[]` (`{ "n" => name,
+    # "r" => [...] }`) and a comparator (`IsIn` / `IsNotIn`). The segment's `r[]`
+    # entries are **bare user conditions**, AND-grouped: the user IS-IN the
+    # segment iff every condition matches. The decision is then optionally
+    # negated by `IsNotIn`.
+    #
+    # The **sensitive-comparator context salt is the segment NAME** (`n`), NOT
+    # the setting key — the crucial divergence from a user condition; getting it
+    # wrong silently breaks every hashed segment row.
+    #
+    # Three-valued outcome: `true` (in segment per the comparator), `false` (not
+    # in segment), or a `Comparators::ValidationError`. An error is returned
+    # **un-negated** — `IsNotIn` never flips an error into a match.
+    module Segments
+      SEGMENT_IS_IN = 0
+      SEGMENT_IS_NOT_IN = 1
+
+      # A malformed segment reference / name — a fatal config error (fail-closed,
+      # caught by the evaluator's rescue-all).
+      class SegmentReferenceError < StandardError; end
+
+      module_function
+
+      # Resolve one segment condition. `evaluate_user_condition` is injected (the
+      # evaluator owns it) so this module has no back-reference to the evaluator;
+      # it evaluates one segment `r[]` user condition with the segment NAME as
+      # the context salt.
+      def evaluate_segment_condition(condition, segments, has_user, surface_missing_user, evaluate_user_condition)
+        # No user → the whole segment condition is the missing-user error
+        # (surfaced once per context), exactly like a user condition.
+        return Comparators.error(surface_missing_user.call) unless has_user
+
+        index = condition["s"]
+        unless index.is_a?(Integer) && !boolean?(index) && index >= 0 && index < segments.length
+          raise SegmentReferenceError, "Segment reference is invalid."
+        end
+
+        segment = segments[index]
+        segment_name = segment["n"]
+        unless segment_name.is_a?(String) && !segment_name.empty?
+          raise SegmentReferenceError,
+                "Segment name is missing."
+        end
+
+        # The segment's `r[]` is an AND-group of BARE user conditions; the
+        # context salt is the segment NAME. Short-circuit on first non-match.
+        in_segment = true
+        (segment["r"] || []).each do |uc|
+          in_segment = evaluate_user_condition.call(uc, segment_name)
+          break if in_segment != true
+        end
+
+        # An error is returned un-negated — IsNotIn never converts an error into
+        # a match (matches common-js: the comparator switch only runs when the
+        # segment result is a clean bool).
+        return in_segment unless [true, false].include?(in_segment)
+
+        condition["c"] == SEGMENT_IS_NOT_IN ? !in_segment : in_segment
+      end
+
+      def boolean?(value)
+        [true, false].include?(value)
+      end
+    end
+  end
+end

data/lib/confeature/internal/semver.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: MIT
+
+module Confeature
+  module Internal
+    # ConfigCat-semantics semver parse + compare. Ported field-for-field from
+    # the spec-117 TS reference (`packages/sdk-shared/src/semver.ts`) and the
+    # spec-118 Python port (`apps/sdk-python/.../semver.py`), which themselves
+    # vendor ConfigCat `common-js` `Semver.ts`. A Ruby semver gem is NOT used —
+    # ConfigCat's strict-parse + precedence edge cases diverge from those gems
+    # and would fail the vendored `testmatrix_semantic*` precedence rows.
+    #
+    # Key behaviours:
+    #   - **Strict (non-loose) parse** of the FULL grammar
+    #     `v?MAJOR.MINOR.PATCH(-prerelease)?(+build)?`, each core component a
+    #     `0|[1-9]\d*` numeric identifier; an optional leading `v` is allowed.
+    #   - **Parse on trim.** Callers parse `value.strip`; {.parse} also trims.
+    #   - **Unparseable → nil**, never an exception. The caller treats nil as a
+    #     validation error (the rule errors and does not match — FR-010), NOT a
+    #     silent false.
+    #   - **Precedence**: numeric major.minor.patch first; then pre-release. A
+    #     version WITHOUT a pre-release ranks HIGHER than one WITH a pre-release.
+    #     Pre-release identifiers compared field-by-field — numeric vs numeric
+    #     numerically; a numeric identifier < an alphanumeric identifier;
+    #     alphanumeric compared ASCII-lexically; when all preceding fields are
+    #     equal, MORE fields rank higher than fewer.
+    #   - **Build metadata is ignored** for precedence (SemVer §10).
+    module Semver
+      NUMERIC_IDENTIFIER = '0|[1-9]\d*'
+      NON_NUMERIC_IDENTIFIER = '\d*[a-zA-Z-][a-zA-Z0-9-]*'
+      MAIN_VERSION = "(#{NUMERIC_IDENTIFIER})\\.(#{NUMERIC_IDENTIFIER})\\.(#{NUMERIC_IDENTIFIER})".freeze
+      PRERELEASE_IDENTIFIER = "(?:#{NUMERIC_IDENTIFIER}|#{NON_NUMERIC_IDENTIFIER})".freeze
+      PRERELEASE = "(?:-(#{PRERELEASE_IDENTIFIER}(?:\\.#{PRERELEASE_IDENTIFIER})*))".freeze
+      BUILD_IDENTIFIER = "[0-9A-Za-z-]+"
+      BUILD = "(?:\\+(#{BUILD_IDENTIFIER}(?:\\.#{BUILD_IDENTIFIER})*))".freeze
+      FULL = /\Av?#{MAIN_VERSION}#{PRERELEASE}?#{BUILD}?\z/
+
+      MAX_LENGTH = 256
+      # Mirrors JS Number.MAX_SAFE_INTEGER (the TS reference's bound).
+      MAX_SAFE_INTEGER = 9_007_199_254_740_991
+
+      NUMERIC_RE = /\A[0-9]+\z/
+
+      # A parsed semver with a ConfigCat-precedence #compare.
+      #
+      # `prerelease` is an Array of Integer (numeric ids) | String;
+      # `build` is an Array of String (ignored for precedence).
+      Version = Struct.new(:version, :major, :minor, :patch, :prerelease, :build, keyword_init: true) do
+        # Compare against `other`: <0 lower, 0 equal, >0 higher. Build metadata
+        # is ignored. Mirrors common-js `SemVer.compare` → `compareMain ||
+        # comparePre`.
+        def compare(other)
+          return 0 if other.version == version
+
+          main = compare_main(other)
+          return main unless main.zero?
+
+          compare_pre(other)
+        end
+
+        private
+
+        def compare_main(other)
+          c = Semver.compare_identifiers(major, other.major)
+          return c unless c.zero?
+
+          c = Semver.compare_identifiers(minor, other.minor)
+          return c unless c.zero?
+
+          Semver.compare_identifiers(patch, other.patch)
+        end
+
+        def compare_pre(other)
+          # A version WITHOUT a pre-release is higher-precedence than one WITH.
+          return -1 if !prerelease.empty? && other.prerelease.empty?
+          return 1 if prerelease.empty? && !other.prerelease.empty?
+          return 0 if prerelease.empty? && other.prerelease.empty?
+
+          i = 0
+          loop do
+            a = i < prerelease.length ? prerelease[i] : nil
+            b = i < other.prerelease.length ? other.prerelease[i] : nil
+            return 0 if a.nil? && b.nil?
+            return 1 if b.nil?
+            return -1 if a.nil?
+
+            if a == b
+              i += 1
+              next
+            end
+            return Semver.compare_identifiers(a, b)
+          end
+        end
+      end
+
+      module_function
+
+      # Compare two pre-release / core identifiers (common-js
+      # `compareIdentifiers`): both numeric → numeric compare; a numeric
+      # identifier is lower-precedence than an alphanumeric one; otherwise
+      # ASCII-lexical.
+      def compare_identifiers(a, b)
+        anum = !NUMERIC_RE.match(a.to_s).nil?
+        bnum = !NUMERIC_RE.match(b.to_s).nil?
+        av = a
+        bv = b
+        if anum && bnum
+          av = a.to_i
+          bv = b.to_i
+        end
+        return 0 if av == bv
+        return -1 if anum && !bnum
+        return 1 if bnum && !anum
+
+        av < bv ? -1 : 1
+      end
+
+      # Parse a version string under ConfigCat's strict grammar. Returns nil on
+      # any failure (length, grammar, out-of-range core component) — never
+      # raises. Trims the input first (parse on trim). The caller surfaces nil
+      # as a validation error (FR-010), never a silent match.
+      def parse(version)
+        trimmed = version.strip
+        return nil if trimmed.length > MAX_LENGTH
+
+        m = FULL.match(trimmed)
+        return nil if m.nil?
+
+        major = m[1].to_i
+        minor = m[2].to_i
+        patch = m[3].to_i
+        return nil if major.negative? || major > MAX_SAFE_INTEGER
+        return nil if minor.negative? || minor > MAX_SAFE_INTEGER
+        return nil if patch.negative? || patch > MAX_SAFE_INTEGER
+
+        prerelease = parse_prerelease(m[4])
+        build = m[5] ? m[5].split(".") : []
+
+        canonical = "#{major}.#{minor}.#{patch}"
+        canonical += "-#{prerelease.join(".")}" unless prerelease.empty?
+        Version.new(
+          version: canonical,
+          major: major, minor: minor, patch: patch,
+          prerelease: prerelease, build: build
+        )
+      end
+
+      # Numberify numeric pre-release ids (matching common-js).
+      def parse_prerelease(raw)
+        return [] if raw.nil?
+
+        raw.split(".").map do |ident|
+          if NUMERIC_RE.match(ident)
+            num = ident.to_i
+            next num if num >= 0 && num < MAX_SAFE_INTEGER
+          end
+          ident
+        end
+      end
+    end
+  end
+end

data/lib/confeature/log_level.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: MIT
+
+require "logger"
+
+module Confeature
+  # Confeature log levels. Int values align with stdlib `Logger`
+  # severity constants so customers can swap between Confeature levels
+  # and stdlib levels transparently.
+  module LogLevel
+    DEBUG   = ::Logger::DEBUG    # 0
+    INFO    = ::Logger::INFO     # 1
+    WARNING = ::Logger::WARN     # 2
+    ERROR   = ::Logger::ERROR    # 3
+    OFF     = ::Logger::UNKNOWN + 1 # 6 — above every stdlib level
+
+    ALL = [DEBUG, INFO, WARNING, ERROR, OFF].freeze
+  end
+end

data/lib/confeature/logger.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: MIT
+
+require "logger"
+
+require_relative "log_level"
+
+module Confeature
+  # Pluggable logger surface.
+  #
+  # Customers integrate by either:
+  #   - keeping the default stderr-backed logger (wraps stdlib
+  #     `::Logger.new($stderr)`), or
+  #   - subclassing `Confeature::Logger` and passing the instance via
+  #     the client's `logger:` constructor kwarg.
+  #
+  # The default level is WARNING (mirrors `configcat`'s default).
+  class Logger
+    attr_reader :level
+
+    def initialize(level: LogLevel::WARNING, io: $stderr)
+      @level = level
+      @logger = ::Logger.new(io)
+      @logger.progname = "confeature"
+      @logger.level = level_to_stdlib(level)
+    end
+
+    def error(message)
+      @logger.error(message) if @level <= LogLevel::ERROR
+    end
+
+    def warning(message)
+      @logger.warn(message) if @level <= LogLevel::WARNING
+    end
+
+    def info(message)
+      @logger.info(message) if @level <= LogLevel::INFO
+    end
+
+    def debug(message)
+      @logger.debug(message) if @level <= LogLevel::DEBUG
+    end
+
+    private
+
+    def level_to_stdlib(level)
+      # LogLevel::OFF maps above ::Logger::UNKNOWN so nothing fires.
+      return ::Logger::UNKNOWN + 1 if level == LogLevel::OFF
+
+      level
+    end
+  end
+
+  # Build the SDK's default logger — stderr-backed, WARNING level.
+  def self.default_logger
+    Logger.new
+  end
+end

data/lib/confeature/polling_mode.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: MIT
+
+module Confeature
+  # Polling-mode factory + value types.
+  #
+  # Mirrors the upstream `configcat` gem's `PollingMode` module: three
+  # factory methods produce frozen value objects that the client wires
+  # into the matching poll service (AutoPoll → daemon thread, LazyLoad
+  # → on-demand staleness check, ManualPoll → caller-driven).
+  module PollingMode
+    AutoPoll = Struct.new(:poll_interval_seconds, :max_init_wait_time_seconds, keyword_init: true) do
+      def to_s
+        "AutoPoll(interval=#{poll_interval_seconds}s, " \
+          "max_init_wait=#{max_init_wait_time_seconds}s)"
+      end
+    end
+
+    LazyLoad = Struct.new(:cache_refresh_interval_seconds, keyword_init: true) do
+      def to_s
+        "LazyLoad(refresh=#{cache_refresh_interval_seconds}s)"
+      end
+    end
+
+    ManualPoll = Class.new do
+      def to_s
+        "ManualPoll"
+      end
+
+      def ==(other)
+        other.is_a?(ManualPoll)
+      end
+      alias_method :eql?, :==
+
+      def hash
+        ManualPoll.hash
+      end
+    end
+
+    # Build an AutoPoll value with the standard ConfigCat defaults.
+    def self.auto_poll(poll_interval: 60, max_init_wait_time: 5)
+      AutoPoll.new(
+        poll_interval_seconds: poll_interval,
+        max_init_wait_time_seconds: max_init_wait_time
+      ).freeze
+    end
+
+    # Build a LazyLoad value with the standard ConfigCat default.
+    def self.lazy_load(cache_refresh_interval: 60)
+      LazyLoad.new(cache_refresh_interval_seconds: cache_refresh_interval).freeze
+    end
+
+    # Singleton ManualPoll value — identity-stable for cheap `equal?`
+    # short-circuits when the client checks the active mode.
+    MANUAL_POLL = ManualPoll.new.freeze
+
+    def self.manual_poll
+      MANUAL_POLL
+    end
+  end
+end

data/lib/confeature/snapshot.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: MIT
+
+require_relative "evaluation_details"
+require_relative "internal/evaluator"
+require_relative "internal/override_eval"
+
+module Confeature
+  # Immutable view of the last-fetched config + a reference to overrides.
+  #
+  # All methods are synchronous. `get_value` consults overrides FIRST
+  # via `Internal::OverrideEval.evaluate_sync`, then falls through to
+  # the cached config + boolean evaluator. This is the spec-036
+  # correctness path that the Ruby SDK inherits from day one.
+  #
+  # `fetch_time` is captured at snapshot construction time so
+  # `EvaluationDetails.fetch_time` is immutable across the snapshot's
+  # life (spec 086 / #266).
+  class Snapshot
+    def initialize(config:, flag_overrides:, default_user:, fetch_time: nil)
+      @config = config
+      @flag_overrides = flag_overrides
+      @default_user = default_user
+      @fetch_time = fetch_time
+      freeze
+    end
+
+    def get_value(key, default, user = nil)
+      # Override path FIRST — spec 036 correctness. Route through the
+      # full-config-aware router (spec 135 / #431) so a rule-bearing
+      # override source resolves targeting rules; the flat-map source is
+      # unchanged.
+      effective_user = user || @default_user
+      found, value = Internal::OverrideEval.evaluate(@flag_overrides, key, default, effective_user)
+      return value if found
+
+      result = Internal::Evaluator.evaluate(
+        @config, key, default, effective_user
+      )
+      result.value
+    end
+
+    def get_all_keys
+      keys = []
+      if @config.is_a?(Hash)
+        settings = @config["f"]
+        keys.concat(settings.keys) if settings.is_a?(Hash)
+      end
+      if @flag_overrides
+        begin
+          override_map = @flag_overrides.data_source.get_overrides_sync
+        rescue StandardError
+          override_map = nil
+        end
+        keys.concat(override_map.keys) if override_map.is_a?(Hash)
+      end
+      keys.uniq.sort
+    end
+
+    # Spec 086 / #266 — typed-envelope mirror of `get_value`.
+    #
+    # For LocalOnly consumers, the override map is the only source of
+    # truth: a key present in the map yields the typed value with
+    # `error: nil`; a missing key yields the default with
+    # `error: "KEY_NOT_FOUND"`. The override-eval helper returns the
+    # default on both KEY_NOT_FOUND and TYPE_MISMATCH branches,
+    # indistinguishable from a legitimate override whose value equals
+    # the default — Snapshot re-queries the map to disambiguate.
+    #
+    # Non-LocalOnly clients route through the evaluator; the
+    # `EvaluationResult.error` string propagates verbatim into the
+    # envelope's `error` field.
+    def get_value_details(key, default, user = nil)
+      effective_user = user || @default_user
+      return local_only_details(key, default, effective_user) if local_only?
+
+      result = Internal::Evaluator.evaluate(@config, key, default, effective_user)
+      matched_rule = result.matched_targeting_rule && TargetingRule.new(result.matched_targeting_rule)
+      matched_option = result.matched_percentage_option && PercentageOption.new(result.matched_percentage_option)
+      EvaluationDetails.new(
+        key: key,
+        value: result.value,
+        variation_id: result.variation_id,
+        user: effective_user,
+        is_default_value: !result.error.nil?,
+        error: result.error,
+        fetch_time: @fetch_time,
+        matched_targeting_rule: matched_rule,
+        matched_percentage_option: matched_option
+      )
+    end
+
+    private
+
+    def local_only?
+      return false if @flag_overrides.nil?
+
+      @flag_overrides.behaviour == OverrideBehaviour::LOCAL_ONLY
+    end
+
+    def local_only_details(key, default, effective_user)
+      # Full-config override source → resolve through the real evaluator
+      # so targeting rules apply AND the served `variation_id` survives
+      # to the PUBLIC details envelope (spec 152 / #475, US2; closes the
+      # #395 gap class). Dispatch on the source TYPE, never the resolved
+      # value, mirroring `get_value`'s `OverrideEval.evaluate` router.
+      found_full, result = Internal::OverrideEval.evaluate_full_config_override_details_sync(
+        @flag_overrides, key, default, effective_user
+      )
+      if found_full
+        matched_rule = result.matched_targeting_rule && TargetingRule.new(result.matched_targeting_rule)
+        matched_option = result.matched_percentage_option && PercentageOption.new(result.matched_percentage_option)
+        return EvaluationDetails.new(
+          key: key,
+          value: result.value,
+          variation_id: result.variation_id,
+          user: effective_user,
+          is_default_value: !result.error.nil?,
+          error: result.error,
+          fetch_time: @fetch_time,
+          matched_targeting_rule: matched_rule,
+          matched_percentage_option: matched_option
+        )
+      end
+
+      found, value = Internal::OverrideEval.evaluate_sync(@flag_overrides, key, default)
+      data_source = @flag_overrides.data_source
+      overrides_map =
+        if data_source.respond_to?(:get_overrides_sync)
+          begin
+            data_source.get_overrides_sync
+          rescue StandardError
+            nil
+          end
+        end
+      present = overrides_map.is_a?(Hash) && overrides_map.key?(key)
+
+      if found && present
+        EvaluationDetails.new(
+          key: key,
+          value: value,
+          user: effective_user,
+          fetch_time: @fetch_time
+        )
+      else
+        EvaluationDetails.new(
+          key: key,
+          value: default,
+          is_default_value: true,
+          error: "KEY_NOT_FOUND",
+          user: effective_user,
+          fetch_time: @fetch_time
+        )
+      end
+    end
+  end
+end