featurehub-sdk 1.3.0 → 2.0.1

data/lib/feature_hub/sdk/{feature_state.rb → feature_state_holder.rb}

@@ -3,7 +3,7 @@
 module FeatureHub
   module Sdk
     # represents internal state of a feature
-    class FeatureState
+    class FeatureStateHolder
       attr_reader :key, :internal_feature_state, :encoded_strategies
 
       def initialize(key, repo, feature_state = nil, parent_state = nil, ctx = nil)
@@ -30,6 +30,10 @@ module FeatureHub
         !(fs.empty? || fs["l"].nil?)
       end
 
+      def present?
+        exists?
+      end
+
       def id
         exists? ? @internal_feature_state["id"] : nil
       end
@@ -40,7 +44,7 @@ module FeatureHub
       end
 
       def with_context(ctx)
-        FeatureState.new(@key, @repo, nil, self, ctx)
+        FeatureStateHolder.new(@key, @repo, nil, self, ctx)
       end
 
       def update_feature_state(feature_state)
@@ -61,19 +65,19 @@ module FeatureHub
       end
 
       def string
-        get_value("STRING")
+        get_value(FeatureValueType::STRING)
       end
 
       def number
-        get_value("NUMBER")
+        get_value(FeatureValueType::NUMBER)
       end
 
       def raw_json
-        get_value("JSON")
+        get_value(FeatureValueType::JSON)
       end
 
       def boolean
-        get_value("BOOLEAN")
+        get_value(FeatureValueType::BOOLEAN)
       end
 
       def flag
@@ -108,9 +112,9 @@ module FeatureHub
 
       def get_value(feature_type)
         unless locked?
-          intercept = @repo.find_interceptor(@key)
+          matched, intercept_value = @repo.find_interceptor(@key, top_feature_state.feature_state)
 
-          return intercept.cast(feature_type) if intercept
+          return intercept_value if matched
         end
 
         fs = top_feature_state
@@ -124,7 +128,7 @@ module FeatureHub
         if @ctx
           matched = @repo.apply(fs.encoded_strategies, @key, fs.id, @ctx)
 
-          return FeatureHub::Sdk::InterceptorValue.new(matched.value).cast(feature_type) if matched.matched
+          return matched.value if matched.matched
         end
 
         state["value"]

data/lib/feature_hub/sdk/interceptors.rb

@@ -12,9 +12,9 @@ module FeatureHub
         return @val if expected_type.nil? || @val.nil?
 
         case expected_type
-        when "BOOLEAN"
+        when FeatureValueType::BOOLEAN
           @val.to_s.downcase.strip == "true"
-        when "NUMBER"
+        when FeatureValueType::NUMBER
           @val.to_s.to_f
         else
           @val.to_s
@@ -25,7 +25,11 @@ module FeatureHub
     # Holds the pattern for a value based interceptor, which could come from a file, or whatever
     # they are not typed
     class ValueInterceptor
-      def intercepted_value(feature_key); end
+      def intercepted_value(_feature_key, _repository, _feature_state)
+        [false, nil]
+      end
+
+      def close; end
     end
 
     # An example of a value interceptor that uses environment variables
@@ -35,13 +39,13 @@ module FeatureHub
         @enabled = ENV.fetch("FEATUREHUB_OVERRIDE_FEATURES", "false") == "true"
       end
 
-      def intercepted_value(feature_key)
+      def intercepted_value(feature_key, _repository, _feature_state)
         if @enabled
           found = ENV.fetch("FEATUREHUB_#{sanitize_feature_name(feature_key.to_s)}", nil)
-          return InterceptorValue.new(found) unless found.nil?
+          return [true, found] unless found.nil?
         end
 
-        nil
+        [false, nil]
       end
 
       private

data/lib/feature_hub/sdk/internal_feature_repository.rb

@@ -8,8 +8,12 @@ module FeatureHub
         nil
       end
 
-      def find_interceptor(_feature_value)
-        nil
+      def value(_key, default_value = nil, _attrs = nil)
+        default_value
+      end
+
+      def find_interceptor(_feature_key, _feature_state = nil)
+        [false, nil]
       end
 
       def ready?
@@ -22,7 +26,7 @@ module FeatureHub
         Applied.new(false, nil)
       end
 
-      def notify(status, data); end
+      def notify(status, data, source = "unknown"); end
     end
   end
 end

data/lib/feature_hub/sdk/local_yaml_interceptor.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+require "concurrent-ruby"
+
+module FeatureHub
+  module Sdk
+    # Reads feature flag overrides from a local YAML file.
+    # The file path is read from FEATUREHUB_LOCAL_YAML or defaults to featurehub-features.yaml.
+    # Pass watch: true to reload the file automatically when it changes.
+    # Expected format:
+    #   flagValues:
+    #     MY_FLAG: true
+    #     MY_STRING: "hello"
+    class LocalYamlValueInterceptor < ValueInterceptor
+      def initialize(opts = nil)
+        super()
+        opts ||= {}
+        @yaml_file = opts[:filename] || ENV.fetch("FEATUREHUB_LOCAL_YAML", "featurehub-features.yaml")
+        @logger = opts[:logger]
+        @mutex = Mutex.new
+        @flag_values = load_flag_values(@yaml_file)
+        @logger&.debug("[featurehubsdk] loaded #{@flag_values.size} feature override(s) from #{@yaml_file}")
+        @watcher = nil
+
+        return unless opts[:watch]
+
+        @last_mtime = File.exist?(@yaml_file) ? File.mtime(@yaml_file) : nil
+        watch_interval = opts[:watch_interval] || 5
+        @watcher = Concurrent::TimerTask.new(execution_interval: watch_interval, run_now: false) do
+          reload_if_changed
+        end
+        @watcher.execute
+      end
+
+      def intercepted_value(feature_key, _repository, feature_state)
+        key = feature_key.to_s
+        flag_values = @mutex.synchronize { @flag_values }
+        return [false, nil] unless flag_values.key?(key)
+
+        value = flag_values[key]
+
+        return [false, nil] if feature_state && yaml_value_type(value) != feature_state["type"]
+
+        [true, cast_value(value)]
+      end
+
+      def close
+        return if @watcher.nil?
+
+        @watcher.shutdown
+        @watcher = nil
+      end
+
+      private
+
+      def reload_if_changed
+        return unless File.exist?(@yaml_file)
+
+        current_mtime = File.mtime(@yaml_file)
+        return if current_mtime == @last_mtime
+
+        @last_mtime = current_mtime
+        new_values = load_flag_values(@yaml_file)
+        @logger&.debug("[featurehubsdk] reloaded #{new_values.size} feature override(s) from #{@yaml_file}")
+        @mutex.synchronize { @flag_values = new_values }
+      end
+
+      def load_flag_values(yaml_file)
+        return {} unless File.exist?(yaml_file)
+
+        data = YAML.safe_load(File.read(yaml_file))
+        data&.fetch("flagValues", {}) || {}
+      rescue StandardError
+        {}
+      end
+
+      def yaml_value_type(value)
+        case value
+        when true, false
+          FeatureValueType::BOOLEAN
+        when Integer, Float
+          FeatureValueType::NUMBER
+        when String
+          FeatureValueType::STRING
+        else
+          FeatureValueType::JSON
+        end
+      end
+
+      def cast_value(value)
+        return value.to_f if value.is_a?(Integer) || value.is_a?(Float)
+
+        value
+      end
+    end
+  end
+end

data/lib/feature_hub/sdk/local_yaml_store.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+require "securerandom"
+
+module FeatureHub
+  module Sdk
+    # Reads feature flags from a local YAML file and loads them into a FeatureHubRepository,
+    # allowing the SDK to operate without a FeatureHub Edge server.
+    # Implements RawUpdateFeatureListener but silently ignores all incoming update callbacks —
+    # the file is the single source of truth and is read exactly once at initialization.
+    #
+    # Expected YAML format (same as LocalYamlValueInterceptor):
+    #   flagValues:
+    #     MY_FLAG: true
+    #     MY_STRING: "hello"
+    #     MY_NUMBER: 42
+    class LocalYamlStore < RawUpdateFeatureListener
+      SOURCE = "local-yaml"
+
+      def initialize(repository, filename = nil)
+        super()
+        @environment_id = SecureRandom.uuid
+        yaml_file = filename || ENV.fetch("FEATUREHUB_LOCAL_YAML", "featurehub-features.yaml")
+        features = load_features(yaml_file)
+        repository.notify("features", features, SOURCE) if features
+      end
+
+      private
+
+      def load_features(yaml_file)
+        return nil unless File.exist?(yaml_file)
+
+        data = YAML.safe_load(File.read(yaml_file))
+        flag_values = data&.fetch("flagValues", {}) || {}
+        flag_values.map { |key, value| build_feature_state(key.to_s, value) }
+      rescue StandardError
+        nil
+      end
+
+      def build_feature_state(key, value)
+        {
+          "id" => SecureRandom.uuid,
+          "key" => key,
+          "l" => false,
+          "version" => 1,
+          "type" => feature_type(value),
+          "value" => cast_value(value),
+          "environmentId" => @environment_id
+        }
+      end
+
+      def feature_type(value)
+        case value
+        when true, false then FeatureValueType::BOOLEAN
+        when Integer, Float then FeatureValueType::NUMBER
+        when String then FeatureValueType::STRING
+        else FeatureValueType::JSON
+        end
+      end
+
+      def cast_value(value)
+        return value.to_f if value.is_a?(Integer) || value.is_a?(Float)
+        return value.to_json if value.is_a?(Hash) || value.is_a?(Array)
+
+        value
+      end
+    end
+  end
+end

data/lib/feature_hub/sdk/poll_edge_service.rb

@@ -10,18 +10,13 @@ module FeatureHub
   module Sdk
     # uses a periodic polling mechanism to get updates
     class PollingEdgeService < EdgeService
-      attr_reader :repository, :api_keys, :edge_url, :interval, :stopped, :etag, :cancel, :sha_context
+      attr_reader :api_keys, :edge_url, :interval, :stopped, :etag, :cancel, :sha_context
 
       def initialize(repository, api_keys, edge_url, interval, logger = nil)
-        super(repository, api_keys, edge_url)
+        super(repository, api_keys, edge_url, logger)
 
-        @repository = repository
-        @api_keys = api_keys
-        @edge_url = edge_url
         @interval = interval
 
-        @logger = logger || FeatureHub::Sdk.default_logger
-
         @task = nil
         @cancel = false
         @context = nil
@@ -73,7 +68,7 @@ module FeatureHub
       def poll_with_interval
         return if @cancel || !@task.nil? || @stopped
 
-        @logger.debug("starting polling for #{determine_request_url}")
+        @logger&.debug("starting polling for #{determine_request_url}")
         @task = Concurrent::TimerTask.new(execution_interval: @interval, run_now: false) do
           get_updates
         end
@@ -112,7 +107,7 @@ module FeatureHub
         headers["x-featurehub"] = @context unless @context.nil?
         headers["if-none-match"] = @etag unless @etag.nil?
 
-        @logger.debug("polling for #{url}")
+        @logger&.debug("polling for #{url}")
         resp = @conn.get url, {}, headers
         case resp.status
         when 200
@@ -120,14 +115,14 @@ module FeatureHub
         when 236
           stopped_task
           success(resp)
-        when 404 # no such key
-          @repository.notify("failed", nil)
+        when 404, 400 # no such key
+          @repository.notify("failed", nil, "polling")
           cancel_task
-          @logger.error("featurehub: key does not exist, stopping polling")
+          @logger&.error("featurehub: key does not exist, stopping polling")
         when 503 # dacha busy
-          @logger.debug("featurehub: dacha is busy, trying again")
+          @logger&.debug("featurehub: dacha is busy, trying again")
         else
-          @logger.debug("featurehub: unknown error #{resp.status}")
+          @logger&.debug("featurehub: unknown error #{resp.status}") if resp.status != 304
         end
       end
 
@@ -143,7 +138,7 @@ module FeatureHub
 
       def process_results(data)
         data.each do |environment|
-          @repository.notify("features", environment["features"]) if environment
+          @repository.notify("features", environment["features"], "polling") if environment
         end
       end
 

data/lib/feature_hub/sdk/raw_update_feature_listener.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module FeatureHub
+  module Sdk
+    # Base class for listening to raw feature update events from edge services.
+    # Subclass and override the methods you care about.
+    class RawUpdateFeatureListener
+      def delete_feature(_feature, _source); end
+
+      def process_updates(_features, _source); end
+
+      def process_update(_feature, _source); end
+
+      def close; end
+
+      def config_changed; end
+    end
+  end
+end

data/lib/feature_hub/sdk/redis_session_store.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "json"
+require "concurrent-ruby"
+
+module FeatureHub
+  module Sdk
+    # Persists feature values from a FeatureHubRepository in Redis so they survive
+    # process restarts and are shared across multiple processes.
+    #
+    # WARNING: Do not use with server-evaluated features. Each server-evaluated
+    # context sends different resolved values; storing them in a shared Redis key
+    # will cause processes to overwrite each other's feature states.
+    #
+    # On initialization the store checks Redis for previously saved features and
+    # replays them into the repository. It then listens for live updates via
+    # RawUpdateFeatureListener and writes newer versions back to Redis. A periodic
+    # timer re-reads all features from Redis so that updates published by other
+    # processes are picked up automatically.
+    #
+    # Options (symbol keys):
+    #   :namespace  - Redis db index (default: 0)
+    #   :prefix     - key prefix for all Redis keys (default: "featurehub")
+    #   :timeout    - seconds between periodic reloads (default: 30)
+    class RedisSessionStore < RawUpdateFeatureListener
+      SOURCE = "redis-store"
+
+      def initialize(connection_string, repository, opts = nil)
+        super()
+
+        opts ||= {}
+        @repository = repository
+        @prefix = opts[:prefix] || "featurehub"
+        @timeout = opts[:timeout] || 30
+        @namespace = opts[:namespace] || 0
+        @password = opts[:password]
+        @logger = opts[:logger]
+        @task = nil
+
+        return unless redis_available?
+
+        redis_opts = { url: connection_string, db: @namespace }
+        redis_opts[:password] = @password if @password
+        @redis = Redis.new(**redis_opts)
+        load_from_redis
+        start_timer
+      end
+
+      def process_updates(features, source)
+        return if source == SOURCE || !redis_available?
+
+        features.each { |f| store_feature(f) }
+      end
+
+      def process_update(feature, source)
+        return if source == SOURCE || !redis_available?
+
+        store_feature(feature)
+      end
+
+      def delete_feature(feature, source)
+        return if source == SOURCE || !redis_available? || !feature["id"]
+
+        @redis.srem(ids_key, feature["id"])
+        @redis.del(feature_key(feature["id"]))
+      end
+
+      def close
+        return if @task.nil?
+
+        @task.shutdown
+        @task = nil
+      end
+
+      private
+
+      def redis_available?
+        @redis_available ||= begin
+          require "redis"
+          true
+        rescue LoadError
+          false
+        end
+      end
+
+      def load_from_redis
+        ids = @redis.smembers(ids_key)
+        return if ids.empty?
+
+        features = ids.filter_map do |id|
+          json = @redis.get(feature_key(id))
+          JSON.parse(json) if json
+        end
+
+        return if features.empty?
+
+        @logger&.debug("[featurehubsdk] loading #{features.size} feature(s) from redis")
+        @repository.notify("features", features, SOURCE)
+      end
+
+      def start_timer
+        @task = Concurrent::TimerTask.new(execution_interval: @timeout, run_now: false) do
+          load_from_redis
+        end
+        @task.execute
+      end
+
+      def store_feature(feature)
+        return unless feature && feature["id"] && feature["key"]
+
+        existing_json = @redis.get(feature_key(feature["id"]))
+        if existing_json
+          existing = JSON.parse(existing_json)
+          return if existing["version"].to_i >= feature["version"].to_i
+        end
+
+        @redis.sadd(ids_key, feature["id"])
+        @redis.set(feature_key(feature["id"]), feature.to_json)
+      end
+
+      def ids_key
+        "#{@prefix}_ids"
+      end
+
+      def feature_key(id)
+        "#{@prefix}_#{id}"
+      end
+    end
+  end
+end

data/lib/feature_hub/sdk/strategy_attributes.rb

@@ -213,6 +213,13 @@ module FeatureHub
       Embedded = "embedded"
     end
 
+    module FeatureValueType
+      BOOLEAN = "BOOLEAN"
+      JSON = "JSON"
+      STRING = "STRING"
+      NUMBER = "NUMBER"
+    end
+
     module StrategyAttributePlatformName
       Linux = "linux"
       Windows = "windows"

data/lib/feature_hub/sdk/streaming_edge_service.rb

@@ -7,16 +7,14 @@ module FeatureHub
   module Sdk
     # provides a streaming service
     class StreamingEdgeService < FeatureHub::Sdk::EdgeService
-      attr_reader :repository, :sse_client, :url, :stopped
+      attr_reader :sse_client, :url, :stopped
 
       def initialize(repository, api_keys, edge_url, logger = nil)
-        super(repository, api_keys, edge_url)
+        super(repository, api_keys, edge_url, logger)
 
         @url = "#{edge_url}features/#{api_keys[0]}"
-        @repository = repository
         @sse_client = nil
         @context = nil
-        @logger = logger || FeatureHub::Sdk.default_logger
       end
 
       def closed
@@ -58,7 +56,7 @@ module FeatureHub
       end
 
       def start_streaming
-        @logger.debug("streaming from #{@url}")
+        @logger&.debug("streaming from #{@url}")
         # we can get an error before returning the new() function and get a race condition on the close
         must_close = false
         @sse_client = SSE::Client.new(@url) do |client|
@@ -68,12 +66,12 @@ module FeatureHub
             if event.type == "config"
               process_config(json_data)
             else
-              @repository.notify(event.type, json_data)
+              @repository.notify(event.type, json_data, "streaming")
             end
           end
           client.on_error do |error|
             if error.is_a?(SSE::Errors::HTTPStatusError) && (error.status == 404)
-              @repository.notify("failure", nil)
+              @repository.notify("failure", nil, "streaming")
               close
               must_close = true
             end

data/lib/feature_hub/sdk/version.rb

@@ -3,15 +3,6 @@
 module FeatureHub
   # already documented elsewhere
   module Sdk
-    VERSION = "1.3.0"
-
-    def default_logger
-      log = ::Logger.new($stdout)
-      log.level = ::Logger::WARN
-      log.progname = "featurehub-sdk"
-      log
-    end
-
-    module_function :default_logger
+    VERSION = "2.0.1"
   end
 end

data/lib/featurehub-sdk.rb

@@ -9,9 +9,13 @@ require_relative "feature_hub/sdk/context"
 require_relative "feature_hub/sdk/feature_hub_config"
 require_relative "feature_hub/sdk/internal_feature_repository"
 require_relative "feature_hub/sdk/feature_repository"
-require_relative "feature_hub/sdk/feature_state"
+require_relative "feature_hub/sdk/feature_state_holder"
 require_relative "feature_hub/sdk/interceptors"
 require_relative "feature_hub/sdk/strategy_attributes"
+require_relative "feature_hub/sdk/local_yaml_interceptor"
+require_relative "feature_hub/sdk/raw_update_feature_listener"
+require_relative "feature_hub/sdk/local_yaml_store"
+require_relative "feature_hub/sdk/redis_session_store"
 require_relative "feature_hub/sdk/impl/strategy_wrappers"
 require_relative "feature_hub/sdk/poll_edge_service"
 require_relative "feature_hub/sdk/streaming_edge_service"