featurehub-sdk 1.0.0

data/lib/feature_hub/sdk/context.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FeatureHub
+  module Sdk
+    module ContextKeys
+      USERKEY = :userkey
+      SESSION = :session
+      COUNTRY = :country
+      PLATFORM = :platform
+      DEVICE = :device
+      VERSION = :version
+    end
+
+    # the context holding user data
+    class ClientContext
+      attr_reader :repo
+
+      def initialize(repo)
+        @repo = repo
+        @attributes = {}
+      end
+
+      def user_key(value)
+        @attributes[ContextKeys::USERKEY] = [value]
+        self
+      end
+
+      def session_key(value)
+        @attributes[ContextKeys::SESSION] = [value]
+        self
+      end
+
+      def country(value)
+        @attributes[ContextKeys::COUNTRY] = [value]
+        self
+      end
+
+      def device(value)
+        @attributes[ContextKeys::DEVICE] = [value]
+        self
+      end
+
+      def platform(value)
+        @attributes[ContextKeys::PLATFORM] = [value]
+        self
+      end
+
+      def version(value)
+        @attributes[ContextKeys::VERSION] = [value]
+        self
+      end
+
+      # this takes an array parameter
+      def attribute_value(key, values)
+        if values.empty?
+          @attributes.delete(key.to_sym)
+        else
+          @attributes[key.to_sym] = if values.is_a?(Array)
+                                      values
+                                    else
+                                      [values]
+                                    end
+        end
+
+        self
+      end
+
+      def clear
+        @attributes = {}
+        self
+      end
+
+      def get_attr(key, default_val = nil)
+        (@attributes[key.to_sym] || [default_val])[0]
+      end
+
+      def default_percentage_key
+        key = @attributes[ContextKeys::SESSION] || @attributes[ContextKeys::USERKEY]
+        if key.nil? || key.empty?
+          nil
+        else
+          key[0]
+        end
+      end
+
+      def enabled?(key)
+        feature(key).enabled?
+      end
+
+      def feature(key)
+        @repo.feature(key)
+      end
+
+      def set?(key)
+        feature(key).set?
+      end
+
+      def number(key)
+        feature(key).number
+      end
+
+      def string(key)
+        feature(key).string
+      end
+
+      def json(key)
+        data = feature(key).raw_json
+        return JSON.parse(data) if data
+
+        nil
+      end
+
+      def raw_json(key)
+        feature(key).raw_json
+      end
+
+      def flag(key)
+        feature(key).flag
+      end
+
+      def boolean(key)
+        feature(key).boolean
+      end
+
+      def exists?(key)
+        feature(key).exists?
+      end
+
+      def build
+        self
+      end
+
+      def build_sync
+        self
+      end
+    end
+
+    # represents the strategies being evaluated locally
+    class ClientEvalFeatureContext < ClientContext
+      def initialize(repo, edge)
+        super(repo)
+
+        @edge = edge
+      end
+
+      def build
+        @edge.poll
+        self
+      end
+
+      def build_sync
+        self
+      end
+
+      def feature(key)
+        @repo.feature(key).with_context(self)
+      end
+    end
+
+    # context used when evaluating server side
+    class ServerEvalFeatureContext < ClientContext
+      def initialize(repo, edge)
+        super(repo)
+
+        @edge = edge
+        @old_header = nil
+      end
+
+      def build
+        new_header = @attributes.map { |k, v| "#{k}=#{URI.encode_www_form_component(v[0].to_s)}" } * "&"
+
+        if @old_header.nil? && new_header.empty?
+          @edge.poll
+        elsif new_header != @old_header
+          @old_header = new_header
+          @repo.not_ready!
+
+          @edge.context_change(new_header)
+        end
+
+        self
+      end
+
+      def build_sync
+        build
+      end
+    end
+  end
+end

data/lib/feature_hub/sdk/feature_hub_config.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module FeatureHub
+  module Sdk
+    # interface style definition for all edge services
+    class EdgeService
+      # abstract
+      def initialize(repository, api_keys, edge_url, logger = nil) end
+
+      # abstract
+      def poll; end
+
+      # abstract
+      def context_change(new_header) end
+
+      # abstract
+      def close; end
+    end
+
+    # central dispatch class for FeatureHub SDK
+    class FeatureHubConfig
+      attr_reader :edge_url, :api_keys, :client_evaluated, :logger
+
+      def initialize(edge_url, api_keys, repository = nil, edge_provider = nil, logger = nil)
+        raise "edge_url is not set to a valid string" if edge_url.nil? || edge_url.strip.empty?
+
+        raise "api_keys must be an array of API keys" if api_keys.nil? || !api_keys.is_a?(Array) || api_keys.empty?
+
+        detect_client_evaluated(api_keys)
+
+        @edge_url = parse_edge_url(edge_url)
+        @api_keys = api_keys
+        @repository = repository || FeatureHub::Sdk::FeatureHubRepository.new
+        @edge_service_provider = edge_provider || method(:create_default_provider)
+        @logger = logger || FeatureHub::Sdk.default_logger
+      end
+
+      def repository(repo = nil)
+        @repository = repo || @repository
+      end
+
+      def init
+        get_or_create_edge_service.poll
+        self
+      end
+
+      def force_new_edge_service
+        if @edge_service
+          @edge_service&.close
+          @edge_service = nil
+        end
+
+        get_or_create_edge_service
+      end
+
+      # rubocop:disable Naming/AccessorMethodName
+      def get_or_create_edge_service
+        @edge_service = create_edge_service if @edge_service.nil?
+
+        @edge_service
+      end
+      # rubocop:enable Naming/AccessorMethodName
+
+      def edge_service_provider(edge_provider = nil)
+        return @edge_service_provider if edge_provider.nil?
+
+        @edge_service_provider = edge_provider
+
+        if @edge_service
+          @edge_service&.close
+          @edge_service = nil
+        end
+
+        edge_provider
+      end
+
+      def use_polling_edge_service(interval = ENV.fetch("FEATUREHUB_POLL_INTERVAL", "30").to_i); end
+
+      def new_context
+        get_or_create_edge_service
+
+        if @client_evaluated
+          ClientEvalFeatureContext.new(@repository, @edge_service)
+        else
+          ServerEvalFeatureContext.new(@repository, @edge_service)
+        end
+      end
+
+      def close
+        return if @edge_service.nil?
+
+        @edge_service.close
+        @edge_service = nil
+      end
+
+      private
+
+      def create_edge_service
+        @edge_service_provider.call(@repository, @api_keys, @edge_url, @logger)
+      end
+
+      def create_default_provider(repo, api_keys, edge_url, logger)
+        # FeatureHub::Sdk::PollingEdgeService.new(repo, api_keys, edge_url, 10, logger)
+        FeatureHub::Sdk::StreamingEdgeService.new(repo, api_keys, edge_url, logger)
+      end
+
+      # rubocop:disable Style/GuardClause
+      def detect_client_evaluated(api_keys)
+        @client_evaluated = !api_keys.detect { |k| k.include?("*") }.nil?
+        if api_keys.detect { |k| (@client_evaluated && !k.include?("*")) || (!@client_evaluated && k.include?("*")) }
+          raise "api keys must all be of one type"
+        end
+      end
+      # rubocop:enable Style/GuardClause
+
+      def parse_edge_url(edge_url)
+        if edge_url[-1] == "/"
+          edge_url
+        else
+          "#{edge_url}/"
+        end
+      end
+    end
+  end
+end

data/lib/feature_hub/sdk/feature_repository.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module FeatureHub
+  module Sdk
+    # the core implementation of a feature repository
+    class FeatureHubRepository < InternalFeatureRepository
+      attr_reader :features
+
+      def initialize(apply_features = nil)
+        super()
+        @strategy_matcher = apply_features || FeatureHub::Sdk::Impl::ApplyFeature.new
+        @interceptors = []
+        @features = {}
+        @ready = false
+      end
+
+      def apply(strategies, key, feature_id, context)
+        @strategy_matcher.apply(strategies, key, feature_id, context)
+      end
+
+      def notify(status, data)
+        return unless status
+
+        if status.to_sym == :failed
+          @ready = false
+          return
+        end
+
+        return if data.nil?
+
+        case status.to_sym
+        when :features
+          update_features(data)
+          @ready = true
+        when :feature
+          update_feature(data)
+          @ready = true
+        when :delete_feature
+          delete_feature(data)
+        end
+      end
+
+      def feature(key)
+        sym_key = key.to_sym
+        @features[sym_key] || make_feature_holder(sym_key)
+      end
+
+      def register_interceptor(interceptor)
+        @interceptors.push(interceptor)
+      end
+
+      def find_interceptor(feature_value)
+        @interceptors.find { |interceptor| interceptor.intercepted_value(feature_value) }
+      end
+
+      def ready?
+        @ready
+      end
+
+      def not_ready!
+        @ready = false
+      end
+
+      def extract_feature_state
+        @features.values
+                 .filter(&:exists?)
+                 .map(&:feature_state)
+      end
+
+      private
+
+      def delete_feature(data)
+        return unless data && data["key"]
+
+        feat = @features[data["key"].to_sym]
+
+        feat&.update_feature_state(nil)
+      end
+
+      def make_feature_holder(key)
+        fs = FeatureHub::Sdk::FeatureState.new(key, self)
+        @features[key.to_sym] = fs
+        fs
+      end
+
+      def update_features(data)
+        data.each do |feature|
+          update_feature(feature)
+        end
+      end
+
+      def update_feature(feature_state)
+        return if feature_state.nil? || feature_state["key"].nil?
+
+        key = feature_state["key"].to_sym
+        holder = @features[key]
+        if !holder
+          @features[key] = FeatureHub::Sdk::FeatureState.new(key, self, feature_state)
+          return
+        elsif feature_state["version"] < holder.version
+          return
+        elsif feature_state["version"] == holder.version && feature_state["value"] == holder.value # rubocop:disable Lint/DuplicateBranch
+          return
+        end
+
+        holder.update_feature_state(feature_state)
+      end
+    end
+  end
+end

data/lib/feature_hub/sdk/feature_state.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module FeatureHub
+  module Sdk
+    # represents internal state of a feature
+    class FeatureState
+      attr_reader :key, :internal_feature_state, :encoded_strategies
+
+      def initialize(key, repo, feature_state = nil, parent_state = nil, ctx = nil)
+        @key = key.to_sym
+        @parent_state = parent_state
+        @ctx = ctx
+        @repo = repo
+        @encoded_strategies = []
+
+        if feature_state
+          _set_feature_state(feature_state)
+        else
+          @internal_feature_state = {}
+        end
+      end
+
+      def locked?
+        fs = feature_state
+        exists?(fs) ? fs["l"] : false
+      end
+
+      def exists?(top_feature = nil)
+        fs = top_feature || feature_state
+        !(fs.empty? || fs["l"].nil?)
+      end
+
+      def id
+        exists? ? @internal_feature_state["id"] : nil
+      end
+
+      def feature_type
+        fs = feature_state
+        exists?(fs) ? fs["type"] : nil
+      end
+
+      def with_context(ctx)
+        FeatureState.new(@key, @repo, nil, self, ctx)
+      end
+
+      def update_feature_state(feature_state)
+        _set_feature_state(feature_state)
+      end
+
+      def feature_state
+        top_feature_state.internal_feature_state
+      end
+
+      def value
+        get_value(feature_type)
+      end
+
+      def version
+        fs = feature_state
+        exists?(fs) ? fs["version"] : -1
+      end
+
+      def string
+        get_value("STRING")
+      end
+
+      def number
+        get_value("NUMBER")
+      end
+
+      def raw_json
+        get_value("JSON")
+      end
+
+      def boolean
+        get_value("BOOLEAN")
+      end
+
+      def flag
+        boolean
+      end
+
+      def enabled?
+        boolean == true
+      end
+
+      def set?
+        value != nil?
+      end
+
+      def top_feature_state
+        return @parent_state&.top_feature_state if @parent_state
+
+        self
+      end
+
+      private
+
+      def _feature_state
+        @internal_feature_state
+      end
+
+      def _set_feature_state(feature_state)
+        @internal_feature_state = feature_state || {}
+        found_strategies = feature_state["strategies"] || []
+        @encoded_strategies = found_strategies.map { |s| FeatureHub::Sdk::Impl::RolloutStrategy.new(s) }
+      end
+
+      def get_value(feature_type)
+        unless locked?
+          intercept = @repo.find_interceptor(@key)
+
+          return intercept.cast(feature_type) if intercept
+        end
+
+        fs = top_feature_state
+
+        state = fs.internal_feature_state
+
+        return nil if state.nil?
+
+        return nil if fs.nil? || (!feature_type.nil? && fs.feature_type != feature_type)
+
+        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
+        end
+
+        state["value"]
+      end
+    end
+  end
+end

data/lib/feature_hub/sdk/impl/apply_features.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "time"
+
+module FeatureHub
+  module Sdk
+    module Impl
+      # represents the application of a match, either successfully or not
+      class Applied
+        attr_reader :matched, :value
+
+        def initialize(matched, value)
+          @matched = matched
+          @value = value
+        end
+      end
+
+      # full mechanism for applying client side evaluation
+      class ApplyFeature
+        def initialize(percent_calculator = nil, matcher_repository = nil)
+          @percentage_calculator = percent_calculator || FeatureHub::Sdk::Impl::Murmur3PercentageCalculator.new
+          @matcher_repository = matcher_repository || FeatureHub::Sdk::Impl::MatcherRegistry.new
+        end
+
+        def apply(strategies, _key, feature_value_id, context)
+          return Applied.new(false, nil) if context.nil? || strategies.nil? || strategies.empty?
+
+          percentage = nil
+          percentage_key = nil
+          base_percentage = {}
+          default_percentage_key = context.default_percentage_key
+
+          strategies.each do |rsi|
+            if (rsi.percentage != 0) && (!default_percentage_key.nil? || rsi.percentage_attributes?)
+              new_percentage_key = ApplyFeature.determine_percentage_key(context, rsi)
+
+              base_percentage[new_percentage_key] = 0 if base_percentage[new_percentage_key].nil?
+
+              base_percentage_val = base_percentage[new_percentage_key]
+
+              if percentage.nil? || new_percentage_key != percentage_key
+                percentage_key = new_percentage_key
+                percentage = @percentage_calculator.determine_client_percentage(percentage_key, feature_value_id)
+                use_base_percentage = rsi.attributes? ? 0 : base_percentage_val
+
+                # rubocop:disable Layout/MultilineOperationIndentation
+                if percentage <= (use_base_percentage + rsi.percentage) &&
+                  (!rsi.attributes? || (rsi.attributes? && match_attribute(context, rsi)))
+                  return Applied.new(true, rsi.value)
+                end
+
+                # rubocop:enable Layout/MultilineOperationIndentation
+
+                unless rsi.attributes?
+                  base_percentage[percentage_key] =
+                    base_percentage[percentage_key] + rsi.percentage
+                end
+              end
+            end
+
+            return Applied.new(true, rsi.value) if rsi.percentage.zero? && rsi.attributes? && match_attribute(context,
+                                                                                                              rsi)
+          end
+
+          Applied.new(false, nil)
+        end
+
+        def match_attribute(context, rs_attr)
+          rs_attr.attributes.each do |attr|
+            supplied_value = context.get_attr(attr.field_name)
+            if supplied_value.nil? && attr.field_name.downcase == "now"
+              case attr.field_type
+              when "DATE"
+                supplied_value = Time.new.utc.iso8601[0..9]
+              when "DATETIME"
+                supplied_value = Time.new.utc.iso8601
+              end
+            end
+
+            if attr.values.nil? && supplied_value.nil?
+              return false unless attr.conditional.equals?
+
+              next
+            end
+
+            return false if attr.values.nil? || supplied_value.nil?
+
+            # this attribute has to match or we failed
+            return false unless @matcher_repository.find_matcher(attr).match(supplied_value, attr)
+          end
+
+          true
+        end
+
+        def self.determine_percentage_key(context, rsi)
+          if rsi.percentage_attributes?
+            rsi.percentage_attributes.map { |attr| context.get_attr(attr, "<none>") }.join("$")
+          else
+            context.default_percentage_key
+          end
+        end
+      end
+    end
+  end
+end

data/lib/feature_hub/sdk/impl/murmur3_percentage.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "murmurhash3"
+
+module FeatureHub
+  module Sdk
+    module Impl
+      # consistent across all platforms murmur percentage calculator
+      class Murmur3PercentageCalculator < FeatureHub::Sdk::PercentageCalculator
+        MAX_PERCENTAGE = 1_000_000
+        SEED = 0
+
+        def determine_client_percentage(percentage_text, feature_id)
+          result = MurmurHash3::V32.str_digest(percentage_text + feature_id, SEED).unpack1("L").to_f
+          (result / (2**32) * MAX_PERCENTAGE).floor
+        end
+      end
+    end
+  end
+end