featurehub-sdk 2.0.1 → 2.1.1

data/examples/sinatra/app/application.rb

@@ -5,14 +5,21 @@ require "sinatra"
 require "featurehub-sdk"
 require "json"
 
-def configure_featurehub
+def configure_featurehub(logger)
   puts "FeatureHub SDK Version is #{FeatureHub::Sdk::VERSION}"
 
-  config = FeatureHub::Sdk::FeatureHubConfig.new
+  config = FeatureHub::Sdk::FeatureHubConfig.new(nil, nil, nil, nil, logger)
   repo = config.repository
 
   if ENV["FEATUREHUB_REDIS_STORE"]
-    config.register_raw_update_listener(FeatureHub::Sdk::RedisSessionStore.new(ENV["FEATUREHUB_REDIS_STORE"], repo))
+    FeatureHub::Sdk::RedisSessionStore.new(ENV["FEATUREHUB_REDIS_STORE"], config,
+                                           { logger: logger, refresh_timeout: 3 })
+  end
+
+  if ENV["FEATUREHUB_MEMCACHE_STORE"]
+    FeatureHub::Sdk::MemcacheSessionStore.new(ENV["FEATUREHUB_MEMCACHE_STORE"],
+                                              config, { logger: logger,
+                                                        refresh_timeout: 3 })
   end
 
   if ENV["FEATUREHUB_LOCAL_YAML"]
@@ -20,6 +27,7 @@ def configure_featurehub
     config.register_interceptor(FeatureHub::Sdk::LocalYamlValueInterceptor.new(watch: true))
   end
 
+  puts "connecting to FeatureHub"
   # connect to edge service
   config.init
 end
@@ -34,7 +42,9 @@ class App < Sinatra::Base
     rack = File.new("logs/rack.log", "a+")
     use Rack::CommonLogger, rack
 
-    set :fh_config, configure_featurehub
+    logger = Logger.new($stdout)
+    set :logger, logger
+    set :fh_config, configure_featurehub(logger)
     set :users, {}
   end
 
@@ -42,10 +52,6 @@ class App < Sinatra::Base
     content_type "application/json"
   end
 
-  get("/config/disconnect-edge") do
-    settings.fh_config.close_edge
-  end
-
   # Routes
   # "resolve" a specific todo for this user
   put("/todo/:user/:id/resolve") do
@@ -83,6 +89,7 @@ class App < Sinatra::Base
     if new_todo["title"].nil?
       status(400)
     else
+      settings.logger.debug("todo is #{new_todo}")
       todos.push(Todo.new(new_todo["id"] || 1, new_todo["title"], new_todo["resolved"] || false))
       todo_list(user)
     end
@@ -94,13 +101,26 @@ class App < Sinatra::Base
   end
 
   get("/health/readiness") do
-    if config.repository.ready?
+    if settings.fh_config.repository.ready?
+      "ok"
+    else
+      status(500)
+    end
+  end
+
+  get("/health/liveness") do
+    if settings.fh_config.repository.ready?
       "ok"
     else
       status(500)
     end
   end
 
+  get("/health/disconnect") do
+    settings.fh_config.close_edge
+    status 200
+  end
+
   private
 
   def todo_list(user)
@@ -113,6 +133,7 @@ class App < Sinatra::Base
       new_todos.push(Todo.new(todo.id, process_title(ctx, todo.title), todo.resolved).to_h)
     end
 
+    settings.logger.debug("todos #{new_todos}")
     new_todos.to_json
   end
 
@@ -139,15 +160,6 @@ class App < Sinatra::Base
 
     new_title = new_title.upcase if ctx.enabled?("FEATURE_TITLE_TO_UPPERCASE")
 
-    # puts("features via repository: #{settings.fh_config.repository.features}")
-    # puts("features via edge service: #{settings.fh_config.get_or_create_edge_service.repository}")
-
-    # puts("enabled? #{ctx.repo.features}")
-    puts(ctx.enabled?("FEATURE_TITLE_TO_UPPERCASE"))
-    puts(ctx.flag("FEATURE_TITLE_TO_UPPERCASE"))
-    puts(settings.fh_config.repository.feature("FEATURE_TITLE_TO_UPPERCASE").feature_type)
-    puts(settings.fh_config.repository.feature("FEATURE_TITLE_TO_UPPERCASE").flag)
-
-    new_title&.strip
+    new_title
   end
 end

data/examples/sinatra/conf/nginx.conf

@@ -11,15 +11,6 @@ events {
 http {
 
 
-  passenger_user_switching on;
-  passenger_user root;
-  passenger_default_user root;
-
-  passenger_max_pool_size 6;
-
-  passenger_disable_security_update_check on;
-  passenger_disable_anonymous_telemetry on;
-
   include /etc/nginx/conf/vhosts/*.conf;
   include /etc/nginx/conf.d/*.conf;
 
@@ -33,8 +24,9 @@ http {
     access_log /dev/stdout;
     listen 8099 default_server;
     server_name localhost;
-    root /app/featurehub;
-    passenger_app_root /app/featurehub;
+    root /app/featurehub/examples/sinatra;
+    passenger_app_root /app/featurehub/examples/sinatra;
+    passenger_preload_bundler on;
     passenger_enabled on;
     passenger_startup_file config.ru;
     passenger_app_type rack;

data/examples/sinatra/conf/webapp.conf

@@ -0,0 +1,16 @@
+server {
+    listen 80;
+    server_name localhost;
+    root /app/featurehub/examples/sinatra;
+
+    passenger_enabled on;
+    passenger_user root;
+
+    # If this is a Ruby app, specify a Ruby version:
+    # For Ruby 3.3
+    passenger_ruby /usr/bin/ruby3.3;
+
+    # Nginx has a default limit of 1 MB for request bodies, which also applies
+    # to file uploads. The following line enables uploads of up to 50 MB:
+    #client_max_body_size 50M;
+}

data/examples/sinatra/docker-compose.yaml

@@ -1,6 +1,6 @@
 services:
   party-server:
-    image: featurehub/party-server:1.9.4
+    image: featurehub/party-server:latest
     ports:
       - 8085:8085
     user: 999:999
@@ -12,13 +12,41 @@ services:
     image: redis:latest
     ports:
       - 6379:6379
-  ruby-sinatra:
-    image: ruby-sinatra:latest
+  memcache:
+    image: memcached:1.6-alpine
+    ports:
+      - 11211:11211
+  sinatra:
+    image: todo-server:e2e
+    ports:
+      - 8099:8099
+    environment:
+      RAILS_ENV: production
+      FEATUREHUB_CLIENT_API_KEY: "a1286d73-a23b-4f5b-8fdf-04dd03668fb9/xPlhDYnWlKjjZ3maUPquhOUOmk50gn*Hh8Q5qY6JEURrxtEEjzk"
+      FEATUREHUB_EDGE_URL: http://party-server:8085
+      FEATUREHUB_BASE_URL: http://party-server:8085
+  sinatra-redis:
+    image: todo-server:e2e
+    ports:
+      - 8099:8099
+    environment:
+      FEATUREHUB_POLLING_INTERVAL: "3"
+      FEATUREHUB_CLIENT_API_KEY: "a1286d73-a23b-4f5b-8fdf-04dd03668fb9/xPlhDYnWlKjjZ3maUPquhOUOmk50gn*Hh8Q5qY6JEURrxtEEjzk"
+      FEATUREHUB_EDGE_URL: http://party-server:8085
+      FEATUREHUB_BASE_URL: http://party-server:8085
+      FEATUREHUB_REDIS_STORE: redis://redis:6379
+  sinatra-memcache:
+    image: todo-server:e2e
     ports:
       - 8099:8099
     environment:
+      RAILS_ENV: production
+      FEATUREHUB_POLLING_INTERVAL: "3"
+      FEATUREHUB_CLIENT_API_KEY: "a1286d73-a23b-4f5b-8fdf-04dd03668fb9/xPlhDYnWlKjjZ3maUPquhOUOmk50gn*Hh8Q5qY6JEURrxtEEjzk"
       FEATUREHUB_EDGE_URL: http://party-server:8085
       FEATUREHUB_BASE_URL: http://party-server:8085
-      FEATUREHUB_REDIS_STORE: redis
+      FEATUREHUB_MEMCACHE_STORE: memcache
+    depends_on:
+      - memcache
 volumes:
   featurehub-h2-data:

data/examples/sinatra/start.sh

@@ -1,5 +1,20 @@
-#!/bin/sh
+#!/bin/bash
 RACK_ENV=development
-#export FEATUREHUB_REDIS_STORE=redis://localhost:6379
-export FEATUREHUB_LOCAL_YAML=feature-flags.yaml
-bundle exec thin -R thin.ru -a 0.0.0.0 -p 8099 start
+if [[ "$1" == "redis" ]]; then
+  echo "detected redis"
+  export FEATUREHUB_REDIS_STORE=redis://localhost:6379
+fi
+if [[ "$1" == "memcache" ]]; then
+  echo "detected memcache"
+  export FEATUREHUB_MEMCACHE_STORE=localhost:11211
+fi
+if [[ "$1" == "local" ]]; then
+  echo "detected local yaml"
+  export FEATUREHUB_LOCAL_YAML=feature-flags.yaml
+fi
+PORT=8099
+if [[ "$2" == "sec" ]];  then
+  PORT=8100
+fi
+
+bundle exec thin -R thin.ru -a 0.0.0.0 -p $PORT start

data/featurehub-sdk.gemspec

@@ -35,11 +35,12 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "concurrent-ruby", "~> 1.3"
-  spec.add_dependency "faraday", "~> 2"
-  spec.add_dependency "ld-eventsource", "~> 2.5.1"
+  spec.add_dependency "faraday"
+  spec.add_dependency "ld-eventsource", ">= 2.5.1", "< 2.7.0"
   spec.add_dependency "murmurhash3", "~> 0.1.7"
   spec.add_dependency "sem_version", "~> 2.0.0"
 
   # we will dynamically determine if redis is available
+  spec.add_development_dependency "dalli", "~> 4"
   spec.add_development_dependency "redis", "~> 5"
 end

data/lib/feature_hub/sdk/context.rb

@@ -171,7 +171,7 @@ module FeatureHub
       end
 
       def build
-        @edge.poll
+        @edge&.poll
         self
       end
 
@@ -190,6 +190,8 @@ module FeatureHub
       end
 
       def build
+        return self unless @edge
+
         new_header = @attributes.map { |k, v| "#{k}=#{URI.encode_www_form_component(v[0].to_s)}" } * "&"
 
         if @old_header.nil? && new_header.empty?

data/lib/feature_hub/sdk/feature_hub_config.rb

@@ -25,12 +25,16 @@ module FeatureHub
 
     # central dispatch class for FeatureHub SDK
     class FeatureHubConfig
+      FALLBACK_ENVIRONMENT_ID = "569b0129-d53d-4516-a818-9154af601047"
+
       attr_reader :edge_url, :api_keys, :client_evaluated, :logger
 
       def initialize(edge_url = nil, api_keys = nil, repository = nil, edge_provider = nil, logger = nil) # rubocop:disable Metrics/ParameterLists
         @logger = logger
         @repository = repository || FeatureHub::Sdk::FeatureHubRepository.new(nil, @logger)
 
+        @closed = false
+
         resolved_url = resolve_edge_url(edge_url)
         resolved_keys = resolve_api_keys(api_keys)
 
@@ -84,6 +88,8 @@ module FeatureHub
 
       # rubocop:disable Naming/AccessorMethodName
       def get_or_create_edge_service
+        return nil if @closed
+
         @edge_service = create_edge_service if @edge_service.nil?
 
         @edge_service
@@ -91,6 +97,7 @@ module FeatureHub
       # rubocop:enable Naming/AccessorMethodName
 
       def edge_service_provider(edge_provider = nil)
+        return nil if @closed
         return @edge_service_provider if edge_provider.nil?
 
         @edge_service_provider = edge_provider
@@ -103,7 +110,8 @@ module FeatureHub
         edge_provider
       end
 
-      def use_polling_edge_service(interval = ENV.fetch("FEATUREHUB_POLL_INTERVAL", "30").to_i)
+      def use_polling_edge_service(interval = ENV.fetch("FEATUREHUB_POLL_INTERVAL",
+                                                        ENV.fetch("FEATUREHUB_POLLING_INTERVAL", "30")).to_i)
         @interval = interval
         @edge_service_provider = method(:create_polling_edge_provider)
       end
@@ -111,32 +119,43 @@ module FeatureHub
       def new_context
         get_or_create_edge_service
 
+        edge_service = @closed ? nil : @edge_service
+
         if @client_evaluated
-          ClientEvalFeatureContext.new(@repository, @edge_service)
+          ClientEvalFeatureContext.new(@repository, edge_service)
         else
-          ServerEvalFeatureContext.new(@repository, @edge_service)
+          ServerEvalFeatureContext.new(@repository, edge_service)
         end
       end
 
       def close
         unless @repository.nil?
+          @logger&.info("[featurehubsdk] repository now closed")
           @repository.close
           @repository = nil
         end
 
-        return if @edge_service.nil?
-
-        @edge_service.close
-        @edge_service = nil
+        close_edge
       end
 
       def close_edge
+        return if @closed
+
+        @logger&.info("[featurehubsdk] edge now closed")
+        @closed = true
         return if @edge_service.nil?
 
         @edge_service.close
         @edge_service = nil
       end
 
+      def environment_id
+        return FALLBACK_ENVIRONMENT_ID if @api_keys.empty?
+
+        parts = @api_keys.first.split("/")
+        parts.length == 3 ? parts[1] : parts[0]
+      end
+
       private
 
       def create_edge_service
@@ -148,7 +167,12 @@ module FeatureHub
       end
 
       def create_default_provider(repo, api_keys, edge_url, logger)
-        FeatureHub::Sdk::StreamingEdgeService.new(repo, api_keys, edge_url, logger)
+        if ENV["FEATUREHUB_POLL_INTERVAL"] || ENV["FEATUREHUB_POLLING_INTERVAL"]
+          use_polling_edge_service
+          create_polling_edge_provider(repo, api_keys, edge_url, logger)
+        else
+          FeatureHub::Sdk::StreamingEdgeService.new(repo, api_keys, edge_url, logger)
+        end
       end
 
       def resolve_edge_url(edge_url)

data/lib/feature_hub/sdk/feature_state_holder.rb

@@ -43,6 +43,11 @@ module FeatureHub
         exists?(fs) ? fs["type"] : nil
       end
 
+      def feature_properties
+        fs = feature_state
+        (exists?(fs) ? fs["fp"] : {}) || {}
+      end
+
       def with_context(ctx)
         FeatureStateHolder.new(@key, @repo, nil, self, ctx)
       end
@@ -92,6 +97,12 @@ module FeatureHub
         !value.nil?
       end
 
+      def phantom?
+        return @parent_state&.phantom? unless @parent_state.nil?
+
+        @internal_feature_state.empty?
+      end
+
       def top_feature_state
         return @parent_state&.top_feature_state if @parent_state
 

data/lib/feature_hub/sdk/memcache_session_store.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "json"
+require "concurrent-ruby"
+require_relative "session_store_helpers"
+
+module FeatureHub
+  module Sdk
+    # Optional configuration for MemcacheSessionStore.
+    class MemcacheSessionStoreOptions
+      attr_reader :prefix, :backoff_timeout, :retry_update_count, :refresh_timeout, :logger
+
+      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]
+      end
+    end
+
+    # Persists feature values from a FeatureHubRepository in Memcache so they survive
+    # process restarts and are shared across multiple processes.
+    #
+    # Uses SHA256-based change detection and compare-and-set for multi-process safety.
+    #
+    # WARNING: Do not use with server-evaluated features. Each server-evaluated context
+    # sends different resolved values; storing them in a shared Memcache key will cause
+    # processes to overwrite each other's feature states.
+    #
+    # On initialization the store reads any previously saved features from Memcache 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 MemcacheSessionStore < RawUpdateFeatureListener
+      include SessionStoreHelpers
+
+      SOURCE = "memcache-store"
+
+      # @param connection_or_client [String, Dalli::Client] Memcache connection string or existing client
+      # @param config [FeatureHubConfig] SDK config (provides repository and environment_id)
+      # @param opts [MemcacheSessionStoreOptions, Hash, nil] optional configuration
+      def initialize(connection_or_client, config, opts = nil)
+        super()
+
+        options = opts.is_a?(MemcacheSessionStoreOptions) ? opts : MemcacheSessionStoreOptions.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 dalli_available?
+
+        @dalli = if connection_or_client.is_a?(String)
+                   Dalli::Client.new(connection_or_client, serializer: JSON)
+                 else
+                   connection_or_client
+                 end
+
+        @logger&.debug("[featurehubsdk] started memcache store")
+        Concurrent::Future.execute { load_from_memcache }
+        start_timer
+      end
+
+      def process_updates(features, source)
+        return if source == SOURCE || !dalli_available?
+
+        incoming_sha = calculate_sha(features)
+        return if incoming_sha == @dalli.get(sha_key)
+
+        perform_store_with_retry do |memcache_features|
+          has_newer = features.any? do |f|
+            existing = memcache_features.find { |mf| mf["id"] == f["id"] }
+            existing.nil? || version_of(f) > version_of(existing)
+          end
+          has_newer ? merge_features(memcache_features, features) : nil
+        end
+      end
+
+      def process_update(feature, source)
+        return if source == SOURCE || !dalli_available?
+
+        perform_store_with_retry do |memcache_features|
+          existing = memcache_features.find { |f| f["id"] == feature["id"] }
+          next nil if existing && version_of(existing) >= version_of(feature)
+
+          merge_features(memcache_features, [feature])
+        end
+      end
+
+      def delete_feature(feature, source)
+        return if source == SOURCE || !dalli_available? || !feature["id"]
+
+        perform_store_with_retry do |memcache_features|
+          updated = memcache_features.reject { |f| f["id"] == feature["id"] }
+          updated.length < memcache_features.length ? updated : nil
+        end
+      end
+
+      def close
+        return if @task.nil?
+
+        @task.shutdown
+        @task = nil
+      end
+
+      private
+
+      def dalli_available?
+        @dalli_available ||= begin
+          require "dalli"
+          true
+        rescue LoadError
+          false
+        end
+      end
+
+      def load_from_memcache
+        sha = @dalli.get(sha_key)
+        @mutex.synchronize { @internal_sha = sha }
+
+        features = read_features_from_memcache
+        return if features.empty?
+
+        @logger&.debug("[featurehubsdk] loading #{features.size} feature(s) from memcache")
+        @repository.notify("features", features, SOURCE)
+      end
+
+      def start_timer
+        @task = Concurrent::TimerTask.new(execution_interval: @refresh_timeout, run_now: false) do
+          check_for_updates
+        end
+        @task.execute
+      end
+
+      def check_for_updates
+        return unless dalli_available?
+
+        current_sha = @dalli.get(sha_key)
+        stored_sha = @mutex.synchronize { @internal_sha }
+        return if current_sha == stored_sha
+
+        features = read_features_from_memcache
+        @logger&.debug("[featurehubsdk] detected memcache change, reloading #{features.size} feature(s)")
+        @repository.notify("features", features, SOURCE)
+        @mutex.synchronize { @internal_sha = current_sha }
+      end
+
+      # Computes what to write by yielding the current memcache features to the block.
+      # The block returns the new features array to store, or nil to abort.
+      # Uses compare-and-set with retry to handle multi-process contention.
+      def perform_store_with_retry
+        attempt = 0
+        while attempt < @retry_update_count
+          memcache_features = read_features_from_memcache
+          new_features = yield(memcache_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 = @dalli.get(sha_key)
+
+          if current_sha != current_internal
+            # Another process updated memcache — 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_sha, new_sha, current_internal)
+
+          if stored
+            @dalli.set(features_key, new_features.to_json)
+            @mutex.synchronize { @internal_sha = new_sha }
+            return
+          end
+
+          sleep(@backoff_timeout / 1000.0) unless attempt == @retry_update_count - 1
+          attempt += 1
+        end
+
+        @logger&.warn("[featurehubsdk] failed to update memcache after #{@retry_update_count} retries")
+      end
+
+      def attempt_atomic_write(current_sha, new_sha, current_internal)
+        if current_sha.nil?
+          !!@dalli.add(sha_key, new_sha)
+        else
+          stored = false
+          @dalli.cas(sha_key) do |current|
+            if current == current_internal
+              stored = true
+              new_sha
+            else
+              current # write back same value — harmless no-op if CAS token still valid
+            end
+          end
+          stored
+        end
+      end
+
+      def read_features_from_memcache
+        json = @dalli.get(features_key)
+        return [] unless json
+
+        JSON.parse(json)
+      rescue JSON::ParserError
+        []
+      end
+    end
+  end
+end

data/lib/feature_hub/sdk/poll_edge_service.rb

@@ -108,21 +108,27 @@ module FeatureHub
         headers["if-none-match"] = @etag unless @etag.nil?
 
         @logger&.debug("polling for #{url}")
-        resp = @conn.get url, {}, headers
-        case resp.status
-        when 200
-          success(resp)
-        when 236
-          stopped_task
-          success(resp)
-        when 404, 400 # no such key
-          @repository.notify("failed", nil, "polling")
-          cancel_task
-          @logger&.error("featurehub: key does not exist, stopping polling")
-        when 503 # dacha busy
-          @logger&.debug("featurehub: dacha is busy, trying again")
-        else
-          @logger&.debug("featurehub: unknown error #{resp.status}") if resp.status != 304
+        begin
+          resp = @conn.get url, {}, headers
+          case resp.status
+          when 200
+            success(resp)
+          when 236
+            stopped_task
+            success(resp)
+          when 404, 400 # no such key
+            @repository.notify("failed", nil, "polling")
+            cancel_task
+            @logger&.error("featurehub: key does not exist, stopping polling")
+          when 503 # dacha busy
+            @logger&.debug("featurehub: dacha is busy, trying again")
+          else
+            @logger&.debug("featurehub: unknown error #{resp.status}") if resp.status != 304
+          end
+        rescue StandardError => e
+          # we can get timeout errors for transient network failures, this should not prevent the
+          # next poll from happening however
+          @logger&.error("featurehub: failed to connect or similar error #{e&.message}")
         end
       end