featurehub-sdk 2.0.1 → 2.1.0

data/lib/feature_hub/sdk/redis_session_store.rb

@@ -2,67 +2,110 @@
 
 require "json"
 require "concurrent-ruby"
+require_relative "session_store_helpers"
 
 module FeatureHub
   module Sdk
+    # Optional configuration for RedisSessionStore.
+    class RedisSessionStoreOptions
+      attr_reader :prefix, :backoff_timeout, :retry_update_count, :refresh_timeout, :logger, :db
+
+      def initialize(opts = nil)
+        opts ||= {}
+        @prefix = opts[:prefix] || "featurehub"
+        @backoff_timeout = opts[:backoff_timeout] || 500
+        @retry_update_count = opts[:retry_update_count] || 10
+        @refresh_timeout = opts[:refresh_timeout] || 300
+        @logger = opts[:logger]
+        @db = opts[:db] || 0
+      end
+    end
+
     # 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.
+    # Uses SHA256-based change detection and Redis WATCH/MULTI/EXEC for multi-process safety.
     #
-    # 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.
+    # 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.
     #
-    # 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)
+    # On initialization the store reads any previously saved features from Redis and
+    # replays them into the repository. A periodic timer re-reads the SHA key so that
+    # updates published by other processes are picked up automatically.
     class RedisSessionStore < RawUpdateFeatureListener
+      include SessionStoreHelpers
+
       SOURCE = "redis-store"
 
-      def initialize(connection_string, repository, opts = nil)
+      # @param connection_or_client [String, Array, Object] Redis URL, list of cluster URLs,
+      #   or an existing Redis client
+      # @param config [FeatureHubConfig] SDK config (provides repository and environment_id)
+      # @param opts [RedisSessionStoreOptions, Hash, nil] optional configuration
+      def initialize(connection_or_client, config, opts = nil)
         super()
 
-        opts ||= {}
-        @repository = repository
-        @prefix = opts[:prefix] || "featurehub"
-        @timeout = opts[:timeout] || 30
-        @namespace = opts[:namespace] || 0
-        @password = opts[:password]
-        @logger = opts[:logger]
+        options = opts.is_a?(RedisSessionStoreOptions) ? opts : RedisSessionStoreOptions.new(opts)
+
+        @repository = config.repository
+        @environment_id = config.environment_id
+        @prefix = options.prefix
+        @backoff_timeout = options.backoff_timeout
+        @retry_update_count = options.retry_update_count
+        @refresh_timeout = options.refresh_timeout
+        @internal_sha = nil
+        @mutex = Mutex.new
         @task = nil
+        @logger = options.logger
 
         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
+        @redis = if connection_or_client.is_a?(String)
+                   Redis.new(url: connection_or_client, db: options.db)
+                 else
+                   connection_or_client
+                 end
+
+        config.register_raw_update_listener(self)
+
+        @logger&.debug("[featurehubsdk] started redis store")
+        Concurrent::Future.execute { load_from_redis }
         start_timer
       end
 
       def process_updates(features, source)
         return if source == SOURCE || !redis_available?
 
-        features.each { |f| store_feature(f) }
+        incoming_sha = calculate_sha(features)
+        return if incoming_sha == @redis.get(sha_key)
+
+        perform_store_with_retry do |redis_features|
+          has_newer = features.any? do |f|
+            existing = redis_features.find { |rf| rf["id"] == f["id"] }
+            existing.nil? || version_of(f) > version_of(existing)
+          end
+          has_newer ? merge_features(redis_features, features) : nil
+        end
       end
 
       def process_update(feature, source)
         return if source == SOURCE || !redis_available?
 
-        store_feature(feature)
+        perform_store_with_retry do |redis_features|
+          existing = redis_features.find { |f| f["id"] == feature["id"] }
+          next nil if existing && version_of(existing) >= version_of(feature)
+
+          merge_features(redis_features, [feature])
+        end
       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"]))
+        perform_store_with_retry do |redis_features|
+          updated = redis_features.reject { |f| f["id"] == feature["id"] }
+          updated.length < redis_features.length ? updated : nil
+        end
       end
 
       def close
@@ -84,14 +127,10 @@ module FeatureHub
       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
+        sha = @redis.get(sha_key)
+        @mutex.synchronize { @internal_sha = sha }
 
+        features = read_features_from_redis
         return if features.empty?
 
         @logger&.debug("[featurehubsdk] loading #{features.size} feature(s) from redis")
@@ -99,31 +138,88 @@ module FeatureHub
       end
 
       def start_timer
-        @task = Concurrent::TimerTask.new(execution_interval: @timeout, run_now: false) do
-          load_from_redis
+        @task = Concurrent::TimerTask.new(execution_interval: @refresh_timeout, run_now: false) do
+          check_for_updates
         end
         @task.execute
       end
 
-      def store_feature(feature)
-        return unless feature && feature["id"] && feature["key"]
+      def check_for_updates
+        return unless redis_available?
+
+        current_sha = @redis.get(sha_key)
+        stored_sha = @mutex.synchronize { @internal_sha }
+        return if current_sha == stored_sha
+
+        features = read_features_from_redis
+        @logger&.debug("[featurehubsdk] detected redis change, reloading #{features.size} feature(s)")
+        @repository.notify("features", features, SOURCE)
+        @mutex.synchronize { @internal_sha = current_sha }
+      end
 
-        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
+      # Computes what to write by yielding the current Redis features to the block.
+      # The block returns the new features array to store, or nil to abort.
+      # Uses WATCH/MULTI/EXEC with retry to handle multi-process contention.
+      def perform_store_with_retry
+        attempt = 0
+        while attempt < @retry_update_count
+          redis_features = read_features_from_redis
+          new_features = yield(redis_features)
+          return if new_features.nil?
+
+          new_sha = calculate_sha(new_features)
+          current_internal = @mutex.synchronize { @internal_sha }
+          return if new_sha == current_internal
+
+          current_sha = @redis.get(sha_key)
+
+          if current_sha != current_internal
+            # Another process updated Redis — reload and recheck on next attempt
+            sleep(@backoff_timeout / 1000.0) unless attempt == @retry_update_count - 1
+            attempt += 1
+            next
+          end
+
+          stored = attempt_atomic_write(current_internal, new_sha, new_features)
+
+          if stored
+            @mutex.synchronize { @internal_sha = new_sha }
+            return
+          end
+
+          sleep(@backoff_timeout / 1000.0) unless attempt == @retry_update_count - 1
+          attempt += 1
         end
 
-        @redis.sadd(ids_key, feature["id"])
-        @redis.set(feature_key(feature["id"]), feature.to_json)
+        @logger&.warn("[featurehubsdk] failed to update redis after #{@retry_update_count} retries")
       end
 
-      def ids_key
-        "#{@prefix}_ids"
+      # Uses WATCH + MULTI/EXEC to atomically update both keys only if sha_key has not
+      # been modified since we read it. Returns true if the transaction committed.
+      def attempt_atomic_write(current_internal, new_sha, new_features)
+        @redis.watch(sha_key)
+        current = @redis.get(sha_key)
+
+        unless current == current_internal
+          @redis.unwatch
+          return false
+        end
+
+        result = @redis.multi do |tx|
+          tx.set(features_key, new_features.to_json)
+          tx.set(sha_key, new_sha)
+        end
+
+        result.is_a?(Array)
       end
 
-      def feature_key(id)
-        "#{@prefix}_#{id}"
+      def read_features_from_redis
+        json = @redis.get(features_key)
+        return [] unless json
+
+        JSON.parse(json)
+      rescue JSON::ParserError
+        []
       end
     end
   end

data/lib/feature_hub/sdk/session_store_helpers.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module FeatureHub
+  module Sdk
+    # Shared pure helpers for MemcacheSessionStore and RedisSessionStore.
+    # Both stores rely on SHA256-based change detection and a two-key layout:
+    #   ${prefix}_${environment_id}      → JSON array of FeatureState objects
+    #   ${prefix}_${environment_id}_sha  → SHA256 of "id:version|..." for change detection
+    module SessionStoreHelpers
+      private
+
+      def calculate_sha(features)
+        parts = features.map { |f| "#{f["id"]}:#{version_of(f)}" }.join("|")
+        Digest::SHA256.hexdigest(parts)
+      end
+
+      def merge_features(base, updates)
+        result = base.dup
+        updates.each do |update|
+          idx = result.find_index { |f| f["id"] == update["id"] }
+          if idx
+            result[idx] = update if version_of(update) > version_of(result[idx])
+          else
+            result << update
+          end
+        end
+        result
+      end
+
+      def version_of(feature)
+        (feature["version"] || 0).to_i
+      end
+
+      def features_key
+        "#{@prefix}_#{@environment_id}"
+      end
+
+      def sha_key
+        "#{@prefix}_#{@environment_id}_sha"
+      end
+    end
+  end
+end

data/lib/feature_hub/sdk/version.rb

@@ -3,6 +3,6 @@
 module FeatureHub
   # already documented elsewhere
   module Sdk
-    VERSION = "2.0.1"
+    VERSION = "2.1.0"
   end
 end

data/lib/featurehub-sdk.rb

@@ -15,7 +15,9 @@ 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/session_store_helpers"
 require_relative "feature_hub/sdk/redis_session_store"
+require_relative "feature_hub/sdk/memcache_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"

data/sig/feature_hub/featurehub.rbs

@@ -94,6 +94,8 @@ module FeatureHub
 
       def set?: () -> bool?
 
+      def phantom?: () -> bool
+
       private
 
       def top_feature_state: -> FeatureStateHolder

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: featurehub-sdk
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Richard Vowles
@@ -28,16 +28,16 @@ dependencies:
   name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: ld-eventsource
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: dalli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: redis
   requirement: !ruby/object:Gem::Requirement
@@ -102,6 +116,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".claude/CLAUDE.md"
+- ".dockerignore"
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
@@ -111,6 +126,7 @@ files:
 - Gemfile.lock
 - LICENSE
 - LICENSE.txt
+- Makefile
 - README.md
 - Rakefile
 - examples/rails_example/.env.example
@@ -209,6 +225,7 @@ files:
 - examples/sinatra/build.sh
 - examples/sinatra/conf/nginx.conf
 - examples/sinatra/conf/nsswitch.conf
+- examples/sinatra/conf/webapp.conf
 - examples/sinatra/config.ru
 - examples/sinatra/docker-compose.yaml
 - examples/sinatra/docker_start.sh
@@ -231,10 +248,12 @@ files:
 - lib/feature_hub/sdk/internal_feature_repository.rb
 - lib/feature_hub/sdk/local_yaml_interceptor.rb
 - lib/feature_hub/sdk/local_yaml_store.rb
+- lib/feature_hub/sdk/memcache_session_store.rb
 - lib/feature_hub/sdk/percentage_calc.rb
 - lib/feature_hub/sdk/poll_edge_service.rb
 - lib/feature_hub/sdk/raw_update_feature_listener.rb
 - lib/feature_hub/sdk/redis_session_store.rb
+- lib/feature_hub/sdk/session_store_helpers.rb
 - lib/feature_hub/sdk/strategy_attributes.rb
 - lib/feature_hub/sdk/streaming_edge_service.rb
 - lib/feature_hub/sdk/version.rb