confeature 0.0.0 → 0.1.0

data/lib/confeature/flag_overrides.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: MIT
+
+module Confeature
+  # How flag overrides interact with the remote config.
+  #
+  # Only `LOCAL_ONLY` is wired in v1 — `LOCAL_OVER_REMOTE` and
+  # `REMOTE_OVER_LOCAL` are accepted at the type level and raise
+  # `NotImplementedError` at evaluation time (spec 031 §R8 deferral,
+  # mirrors Python + Go behaviour).
+  module OverrideBehaviour
+    LOCAL_ONLY         = :local_only
+    LOCAL_OVER_REMOTE  = :local_over_remote
+    REMOTE_OVER_LOCAL  = :remote_over_local
+
+    ALL = [LOCAL_ONLY, LOCAL_OVER_REMOTE, REMOTE_OVER_LOCAL].freeze
+  end
+
+  # One slot of a `config_v6.json` setting value record.
+  #
+  # Exactly one of `b`, `s`, `i`, `d` is non-nil for a valid setting.
+  # The override-eval helper picks the first non-nil field in the
+  # B → S → I → D order, matching the TS / Python / Go canonical
+  # behaviour.
+  SettingValue = Struct.new(:b, :s, :i, :d, keyword_init: true) do
+    def empty?
+      b.nil? && s.nil? && i.nil? && d.nil?
+    end
+
+    def picked
+      return b unless b.nil?
+      return s unless s.nil?
+      return i unless i.nil?
+
+      d
+    end
+  end
+
+  # Abstract base for override-data sources. Concrete implementations
+  # MUST provide a `get_overrides_sync` method returning a
+  # `Hash{String => SettingValue}` (or nil to indicate no sync data).
+  class OverrideDataSource
+    def get_overrides_sync
+      raise NotImplementedError, "subclasses must implement #get_overrides_sync"
+    end
+  end
+
+  # In-memory dict-backed override source — the production default.
+  #
+  # Converts each primitive value to a `SettingValue` slot once at
+  # construction time and returns the same map on every call (stable
+  # identity).
+  class MapOverrideDataSource < OverrideDataSource
+    def initialize(overrides)
+      super()
+      raise ArgumentError, "overrides must be a Hash" unless overrides.is_a?(Hash)
+
+      @map = overrides.each_with_object({}) do |(key, value), acc|
+        acc[key.to_s] = self.class.to_setting_value(value)
+      end.freeze
+      freeze
+    end
+
+    def get_overrides_sync
+      @map
+    end
+
+    # Map a primitive override value to its SettingValue slot.
+    #
+    # `TrueClass` / `FalseClass` are checked before `Integer` because
+    # in Ruby `true.is_a?(Integer)` is false (unlike Python), so order
+    # is purely for clarity here, but we keep the explicit ordering to
+    # mirror Python's defensive coding.
+    def self.to_setting_value(value)
+      case value
+      when true, false
+        SettingValue.new(b: value)
+      when Integer
+        SettingValue.new(i: value)
+      when Float
+        SettingValue.new(d: value)
+      when String
+        SettingValue.new(s: value)
+      else
+        raise ArgumentError,
+              "Unsupported override value type: #{value.class}. " \
+              "Supported types are TrueClass/FalseClass, Integer, Float, String."
+      end
+    end
+  end
+
+  # Full-config override source — holds a complete parsed `config_v6`
+  # blob (`{ "p" => ..., "f" => ..., "s" => ... }`) and routes through
+  # the real evaluator offline.
+  #
+  # Spec 135 / #431 (epic #382, US3): the rule-bearing sibling of
+  # `MapOverrideDataSource`. Where the map source emits value-only
+  # `SettingValue` slots, this source retains the WHOLE `{ p, f, s }`
+  # config — salt (`p.s`) + segments (`s`) + rule-bearing settings (`f`)
+  # — so the Ruby evaluator can resolve targeting rules / segments /
+  # prerequisites / percentage options purely from the supplied config,
+  # with no network fetch.
+  #
+  # Additive extension (Principle II): ConfigCat's official Ruby SDK only
+  # exposes a *file-based* full-config override (`LocalFileDataSource`)
+  # plus a value-only `LocalDictionaryDataSource`. This in-memory
+  # full-config form is the runtime-agnostic equivalent, mirroring the
+  # JS federation's `ConfigOverrideDataSource` / the Python +
+  # .NET ports. No ConfigCat-named member is renamed or retyped.
+  #
+  # The whole config Hash is retained (never just `f`) — the spec-129
+  # dropped-salt regression guard (INV-4): percentage bucketing reads
+  # `p.s` and segment conditions read `s`.
+  #
+  # This source intentionally does NOT subclass `OverrideDataSource`'s
+  # value-only `get_overrides_sync` contract semantics (its settings are
+  # rule-bearing config records, not flat `SettingValue` envelopes). The
+  # override router (`Internal::OverrideEval.evaluate`) dispatches on the
+  # source TYPE — a `ConfigOverrideDataSource` always routes through the
+  # evaluator, never the flat-map path — so it is never mis-read as
+  # value-only.
+  class ConfigOverrideDataSource < OverrideDataSource
+    # @param config [Hash] the full parsed `config_v6` blob (`{ p, f, s }`).
+    def initialize(config)
+      super()
+      raise ArgumentError, "config must be a Hash" unless config.is_a?(Hash)
+
+      @config = config
+      freeze
+    end
+
+    # The full parsed `config_v6` blob (`{ p, f, s }`).
+    attr_reader :config
+
+    # Returns the rule-bearing settings map (`f`).
+    #
+    # Exposed so `Snapshot#get_all_keys` / `Client#get_all_values` can
+    # enumerate the override's flag keys. Resolution itself never goes
+    # through this map — the router evaluates the full config through the
+    # real evaluator.
+    def get_overrides_sync
+      settings = @config["f"]
+      settings.is_a?(Hash) ? settings : {}
+    end
+  end
+
+  # (data_source, behaviour) pair passed via the client constructor.
+  FlagOverrides = Struct.new(:data_source, :behaviour, keyword_init: true) do
+    def initialize(data_source:, behaviour:)
+      unless OverrideBehaviour::ALL.include?(behaviour)
+        raise ArgumentError,
+              "behaviour must be one of OverrideBehaviour::LOCAL_ONLY, " \
+              "::LOCAL_OVER_REMOTE, ::REMOTE_OVER_LOCAL; got #{behaviour.inspect}"
+      end
+      super
+      freeze
+    end
+  end
+
+  # Build a `FlagOverrides` from a full `config_v6` blob.
+  #
+  # The in-memory, rule-bearing offline-override factory (spec 135 /
+  # #431). With `OverrideBehaviour::LOCAL_ONLY`,
+  # `get_value(key, default, user)` resolves targeting rules / segments /
+  # prerequisites / percentage options purely from `config` through the
+  # real evaluator — no network fetch.
+  #
+  # Additive (Principle II): mirrors the JS federation's
+  # `createFlagOverridesFromConfig` and the Python / .NET ports.
+  # ConfigCat's official Ruby SDK exposes the value-only
+  # `LocalDictionaryDataSource` + the file-based `LocalFileDataSource`;
+  # this is the in-memory full-config equivalent, so a customer can drive
+  # the full rule engine from a config blob already resident in memory
+  # (the corpus / test-harness use case) on any runtime.
+  #
+  # @param config [Hash] the full parsed `config_v6` blob (`{ p, f, s }`).
+  # @param behaviour [Symbol] one of `OverrideBehaviour::*`.
+  # @return [FlagOverrides]
+  def self.create_flag_overrides_from_config(config, behaviour)
+    FlagOverrides.new(
+      data_source: ConfigOverrideDataSource.new(config),
+      behaviour: behaviour
+    )
+  end
+end

data/lib/confeature/hooks.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Confeature
+  # Subscribe to client lifecycle events. Mirrors ConfigCat's
+  # `ConfigCat::Hooks` 1:1 at the public API surface (constitution
+  # Principle II, epic #268).
+  #
+  # Four hook points map to the JS-family reference contract:
+  # `client_ready`, `config_changed`, `flag_evaluated`, `error`.
+  # Listener exceptions are caught and logged — never escape to the
+  # emitter. Obtain via `Confeature::Client#hooks`.
+  class Hooks
+    def initialize(logger: nil)
+      @logger = logger || Confeature.default_logger
+      @lock = Mutex.new
+      @on_client_ready = []
+      @on_config_changed = []
+      @on_flag_evaluated = []
+      @on_error = []
+    end
+
+    # Subscribe to the first successful config load.
+    def add_on_client_ready(&block)
+      raise ArgumentError, "block required" unless block_given?
+
+      @lock.synchronize { @on_client_ready << block }
+      nil
+    end
+
+    # Subscribe to every fetched config (`config` is the settings hash).
+    def add_on_config_changed(&block)
+      raise ArgumentError, "block required" unless block_given?
+
+      @lock.synchronize { @on_config_changed << block }
+      nil
+    end
+
+    # Subscribe to every `EvaluationDetails` produced by `get_value_details`.
+    def add_on_flag_evaluated(&block)
+      raise ArgumentError, "block required" unless block_given?
+
+      @lock.synchronize { @on_flag_evaluated << block }
+      nil
+    end
+
+    # Subscribe to non-fatal SDK errors (HTTP failures, cache I/O).
+    def add_on_error(&block)
+      raise ArgumentError, "block required" unless block_given?
+
+      @lock.synchronize { @on_error << block }
+      nil
+    end
+
+    # --- internal invokers ----------------------------------------------
+
+    def invoke_on_client_ready
+      callbacks = @lock.synchronize { @on_client_ready.dup }
+      callbacks.each { |cb| safe_call(cb, :on_client_ready) }
+    end
+
+    def invoke_on_config_changed(config)
+      callbacks = @lock.synchronize { @on_config_changed.dup }
+      callbacks.each { |cb| safe_call(cb, :on_config_changed, config) }
+    end
+
+    def invoke_on_flag_evaluated(details)
+      callbacks = @lock.synchronize { @on_flag_evaluated.dup }
+      callbacks.each { |cb| safe_call(cb, :on_flag_evaluated, details) }
+    end
+
+    def invoke_on_error(message)
+      callbacks = @lock.synchronize { @on_error.dup }
+      callbacks.each { |cb| safe_call(cb, :on_error, message) }
+    end
+
+    private
+
+    def safe_call(callback, name, *args)
+      callback.call(*args)
+    rescue StandardError => e
+      @logger.error("Hooks: #{name} listener raised: #{e.class}: #{e.message}")
+    end
+  end
+end

data/lib/confeature/internal/cache.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: MIT
+
+require "fileutils"
+require "json"
+
+require_relative "sdk_key"
+
+module Confeature
+  module Internal
+    # Filesystem + memory cache for the latest `config_v6.json` body
+    # + ETag.
+    #
+    # Default cache dir: `ENV["XDG_CACHE_HOME"] || File.join(Dir.home,
+    # ".cache")` joined with `confeature`. Customers override via the
+    # client's `cache_directory:` kwarg (FR-014). When the cache
+    # directory is not writable, the implementation emits a single
+    # WARNING log entry and falls back to a process-local memory cache
+    # without further filesystem attempts (FR-012).
+    module Cache
+      CacheEntry = Struct.new(:body, :etag, :fetched_at, keyword_init: true)
+
+      def self.now_seconds
+        Time.now.to_f
+      end
+
+      # Default platform cache dir resolution. Mirrors the
+      # XDG-base-dir spec: prefer XDG_CACHE_HOME if set + non-empty,
+      # else `~/.cache`. Returns nil if Dir.home is unavailable.
+      def self.default_cache_dir
+        xdg = ENV.fetch("XDG_CACHE_HOME", nil)
+        base = xdg && !xdg.empty? ? xdg : File.join(Dir.home, ".cache")
+        File.join(base, "confeature")
+      rescue ArgumentError
+        # Dir.home raises ArgumentError when HOME is unset. Treat that
+        # as "no filesystem cache available" — caller falls back to
+        # memory.
+        nil
+      end
+
+      # Abstract base — subclasses provide read / write.
+      class ConfigCache
+        def read
+          raise NotImplementedError, "subclasses must implement #read"
+        end
+
+        def write(_entry)
+          raise NotImplementedError, "subclasses must implement #write"
+        end
+      end
+
+      # In-process cache — also the fallback when the filesystem
+      # refuses.
+      class InMemoryCache < ConfigCache
+        def initialize
+          super
+          @entry = nil
+          @mutex = Mutex.new
+        end
+
+        def read
+          @mutex.synchronize { @entry }
+        end
+
+        def write(entry)
+          @mutex.synchronize { @entry = entry }
+        end
+      end
+
+      # Persists CacheEntry as JSON at
+      # `{cache_dir}/confeature-{cache_key_tail}.json`.
+      #
+      # On any IO error during write, switches the instance into
+      # memory-only mode and emits a single WARNING log entry.
+      # Subsequent reads/writes use the in-memory entry — the
+      # filesystem is never retried (per FR-012).
+      class FilesystemCache < ConfigCache
+        attr_reader :file_path
+
+        def initialize(cache_dir:, cache_key:, sdk_key:, logger:)
+          super()
+          @sdk_key = sdk_key
+          @logger = logger
+          cache_key_tail = cache_key.split(":").last
+          @cache_dir = cache_dir
+          @file_path = File.join(cache_dir, "confeature-#{cache_key_tail}.json")
+          @memory = InMemoryCache.new
+          @fallback_triggered = false
+          @mutex = Mutex.new
+        end
+
+        def read
+          return @memory.read if @fallback_triggered
+          return @memory.read unless File.exist?(@file_path)
+
+          begin
+            payload = JSON.parse(File.read(@file_path, encoding: "UTF-8"))
+          rescue StandardError => e
+            @logger.warning(
+              "FilesystemCache.read: failed to load #{@file_path} " \
+              "(sdkKey=#{SdkKey.redact(@sdk_key)}): #{e.class}"
+            )
+            return @memory.read
+          end
+
+          begin
+            CacheEntry.new(
+              body: payload.fetch("body"),
+              etag: payload["etag"],
+              fetched_at: payload["fetched_at"].to_f
+            )
+          rescue StandardError => e
+            @logger.warning(
+              "FilesystemCache.read: malformed cache file #{@file_path} " \
+              "(sdkKey=#{SdkKey.redact(@sdk_key)}): #{e.class}"
+            )
+            nil
+          end
+        end
+
+        def write(entry)
+          @memory.write(entry)
+          return if @fallback_triggered
+
+          @mutex.synchronize do
+            FileUtils.mkdir_p(@cache_dir)
+            payload = JSON.generate(
+              "body" => entry.body,
+              "etag" => entry.etag,
+              "fetched_at" => entry.fetched_at
+            )
+            tmp = "#{@file_path}.tmp"
+            File.write(tmp, payload, encoding: "UTF-8")
+            File.rename(tmp, @file_path)
+          end
+        rescue SystemCallError, IOError => e
+          @fallback_triggered = true
+          @logger.warning(
+            "FilesystemCache.write: filesystem unwritable for #{@file_path} " \
+            "(sdkKey=#{SdkKey.redact(@sdk_key)}): #{e.class}. " \
+            "Falling back to memory-only cache for this client."
+          )
+        end
+      end
+
+      # Factory: build the right cache flavour for the supplied config.
+      # `cache_directory == :memory` (or `nil` when default unavailable)
+      # returns InMemoryCache; otherwise FilesystemCache rooted at the
+      # supplied or default directory.
+      def self.build(cache_directory:, cache_key:, sdk_key:, logger:)
+        return InMemoryCache.new if cache_directory == :memory
+
+        dir = cache_directory || default_cache_dir
+        return InMemoryCache.new if dir.nil?
+
+        FilesystemCache.new(
+          cache_dir: dir,
+          cache_key: cache_key,
+          sdk_key: sdk_key,
+          logger: logger
+        )
+      end
+    end
+  end
+end