flagsmith 2.0.0 → 3.0.0

data/lib/flagsmith/sdk/api_client.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Flagsmith
+  # Ruby client for flagsmith.com
+  class ApiClient
+    extend Forwardable
+
+    HTTP_METHODS_ALLOW_LIST = %i[get post].freeze
+
+    delegate HTTP_METHODS_ALLOW_LIST => :@conn
+
+    def initialize(config)
+      @conn = Faraday.new(url: config.api_url) do |f|
+        build_headers(f, config)
+        f.response :json, parser_options: { symbolize_names: true }
+        f.adapter Faraday.default_adapter
+
+        f.options.timeout = config.request_timeout_seconds
+        configure_logger(f, config)
+        configure_retries(f, config)
+      end
+
+      freeze
+    end
+
+    private
+
+    def build_headers(faraday, config)
+      faraday.headers['Accept'] = 'application/json'
+      faraday.headers['Content-Type'] = 'application/json'
+      faraday.headers['X-Environment-Key'] = config.environment_key
+      faraday.headers.merge(config.custom_headers)
+    end
+
+    def configure_logger(faraday, config)
+      faraday.response :logger, config.logger
+    end
+
+    def configure_retries(faraday, config)
+      return unless config.retries
+
+      faraday.request :retry, { max: config.retries }
+    end
+  end
+end

data/lib/flagsmith/sdk/config.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Flagsmith
+  # Config options shared around Engine
+  class Config
+    DEFAULT_API_URL = 'https://edge.api.flagsmith.com/api/v1/'
+    OPTIONS = %i[
+      environment_key api_url custom_headers request_timeout_seconds enable_local_evaluation
+      environment_refresh_interval_seconds retries enable_analytics default_flag_handler logger
+    ].freeze
+
+    # Available Configs
+    #
+    # == Options:
+    #
+    #   +environment_key+                      - The environment key obtained from Flagsmith
+    #                                            interface
+    #   +api_url+                              - Override the URL of the Flagsmith API to communicate with
+    #   +customer_headers+                     - Additional headers to add to requests made
+    #                                            to the Flagsmith API
+    #   +request_timeout_seconds+              - Number of seconds to wait for a request to
+    #                                            complete before terminating the request
+    #                                            Defaults to 10 seconds
+    #   +enable_local_evaluation+              - Enables local evaluation of flags
+    #   +environment_refresh_interval_seconds+ - If using local evaluation,
+    #                                            specify the interval period between
+    #                                            refreshes of local environment data
+    #   +retries+                              - a faraday retry option to use
+    #                                            on all http requests to the Flagsmith API
+    #   +enable_analytics+                     - if enabled, sends additional requests to the Flagsmith
+    #                                            API to power flag analytics charts
+    #   +default_flag_handler+                 - ruby block which will be used in the case where
+    #                                            flags cannot be retrieved from the API or
+    #                                            a non existent feature is requested.
+    #                                            The searched feature#name will be passed to the block as an argument.
+    #   +logger+                               - Pass your logger, default is Logger.new($stdout)
+    #
+    attr_reader(*OPTIONS)
+
+    def initialize(options)
+      build_config(options)
+
+      freeze
+    end
+
+    def local_evaluation?
+      @enable_local_evaluation
+    end
+
+    def enable_analytics?
+      @enable_analytics
+    end
+
+    def environment_flags_url
+      'flags/'
+    end
+
+    def identities_url
+      'identities/'
+    end
+
+    def environment_url
+      'environment-document/'
+    end
+
+    private
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def build_config(options)
+      opts = options.is_a?(String) ? { environment_key: options } : options
+
+      @environment_key = opts.fetch(:environment_key, Flagsmith::Config.environment_key)
+      @api_url = opts.fetch(:api_url, Flagsmith::Config::DEFAULT_API_URL)
+      @custom_headers = opts.fetch(:custom_headers, {})
+      @request_timeout_seconds = opts.fetch(:request_timeout_seconds, 10)
+      @retries = opts[:retries]
+      @enable_local_evaluation = opts.fetch(:enable_local_evaluation, false)
+      @environment_refresh_interval_seconds = opts.fetch(:environment_refresh_interval_seconds, 60)
+      @enable_analytics = opts.fetch(:enable_analytics, false)
+      @default_flag_handler = opts[:default_flag_handler]
+      @logger = options.fetch(:logger, Logger.new($stdout).tap { |l| l.level = :debug })
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    class << self
+      def environment_key
+        ENV['FLAGSMITH_ENVIRONMENT_KEY']
+      end
+    end
+  end
+end

data/lib/flagsmith/sdk/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Flagsmith
+  class ClientError < StandardError; end
+
+  class APIError < StandardError; end
+
+  class FeatureStateNotFound < StandardError; end
+end

data/lib/flagsmith/sdk/instance_methods.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Flagsmith
+  module SDK
+    # Available Flagsmith Functions
+    module InstanceMethods
+      # Get all the default for flags for the current environment.
+      # @returns Flags object holding all the flags for the current environment.
+      def get_environment_flags # rubocop:disable Naming/AccessorMethodName
+        return environment_flags_from_document if @config.local_evaluation?
+
+        environment_flags_from_api
+      end
+
+      # Get all the flags for the current environment for a given identity. Will also
+      # upsert all traits to the Flagsmith API for future evaluations. Providing a
+      # trait with a value of None will remove the trait from the identity if it exists.
+      #
+      # identifier a unique identifier for the identity in the current
+      # environment, e.g. email address, username, uuid
+      # traits { key => value } is a dictionary of traits to add / update on the identity in
+      # Flagsmith, e.g. { "num_orders": 10 }
+      # returns Flags object holding all the flags for the given identity.
+      def get_identity_flags(identifier, **traits)
+        return get_identity_flags_from_document(identifier, traits) if environment
+
+        get_identity_flags_from_api(identifier, traits)
+      end
+
+      def feature_enabled?(feature_name, default: false)
+        flag = get_environment_flags[feature_name]
+        return default if flag.nil?
+
+        flag.enabled?
+      end
+
+      def feature_enabled_for_identity?(feature_name, user_id, default: false)
+        flag = get_identity_flags(user_id)[feature_name]
+        return default if flag.nil?
+
+        flag.enabled?
+      end
+
+      def get_value(feature_name, default: nil)
+        flag = get_environment_flags[feature_name]
+        return default if flag.nil?
+
+        flag.value
+      end
+
+      def get_value_for_identity(feature_name, user_id = nil, default: nil)
+        flag = get_identity_flags(user_id)[feature_name]
+        return default if flag.nil?
+
+        flag.value
+      end
+
+      private
+
+      def environment_flags_from_document
+        Flagsmith::Flags::Collection.from_feature_state_models(
+          get_environment_feature_states(environment),
+          analytics_processor: analytics_processor,
+          default_flag_handler: default_flag_handler
+        )
+      end
+
+      def get_identity_flags_from_document(identifier, traits = {})
+        identity_model = build_identity_model(identifier, traits)
+
+        Flagsmith::Flags::Collection.from_feature_state_models(
+          get_identity_feature_states(environment, identity_model),
+          analytics_processor: analytics_processor,
+          default_flag_handler: default_flag_handler
+        )
+      end
+
+      def environment_flags_from_api
+        rescue_with_default_handler do
+          api_flags = api_client.get(@config.environment_flags_url).body
+          api_flags = api_flags.select { |flag| flag[:feature_segment].nil? }
+          Flagsmith::Flags::Collection.from_api(
+            api_flags,
+            analytics_processor: analytics_processor,
+            default_flag_handler: default_flag_handler
+          )
+        end
+      end
+
+      def get_identity_flags_from_api(identifier, traits = {})
+        rescue_with_default_handler do
+          data = generate_identities_data(identifier, traits)
+          json_response = api_client.post(@config.identities_url, data.to_json).body
+
+          Flagsmith::Flags::Collection.from_api(
+            json_response[:flags],
+            analytics_processor: analytics_processor,
+            default_flag_handler: default_flag_handler
+          )
+        end
+      end
+
+      def rescue_with_default_handler
+        yield
+      rescue StandardError
+        if default_flag_handler
+          return Flagsmith::Flags::Collection.new(
+            {},
+            default_flag_handler: default_flag_handler
+          )
+        end
+        raise
+      end
+
+      def build_identity_model(identifier, traits = {})
+        unless environment
+          raise Flagsmith::ClientError,
+                'Unable to build identity model when no local environment present.'
+        end
+
+        trait_models = traits.map do |key, value|
+          Flagsmith::Engine::Identities::Trait.new(trait_key: key, trait_value: value)
+        end
+        Flagsmith::Engine::Identity.new(
+          identity_traits: trait_models, environment_api_key: environment_key, identifier: identifier
+        )
+      end
+
+      def generate_identities_data(identifier, traits = {})
+        {
+          identifier: identifier,
+          traits: traits.map { |key, value| { trait_key: key, trait_value: value } }
+        }
+      end
+    end
+  end
+end

data/lib/flagsmith/sdk/intervals.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Flagsmith
+  module SDK
+    # Util functions
+    module Intervals
+      # @return [Thread] return loop thread reference
+      # rubocop:disable Naming/AccessorMethodName
+      def set_interval(delay)
+        Thread.new do
+          loop do
+            sleep delay
+            yield if block_given?
+          end
+        end
+      end
+      # rubocop:enable Naming/AccessorMethodName
+
+      def clear_interval(thread)
+        thread.kill
+      end
+    end
+  end
+end

data/lib/flagsmith/sdk/models/flag.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Flagsmith
+  # Flag object
+  class Flag
+    include Comparable
+
+    attr_reader :enabled, :value, :default, :feature_name, :feature_id
+
+    def initialize(feature_name:, enabled:, value:, feature_id:, default: false)
+      @feature_name = feature_name
+      @feature_id = feature_id
+      @enabled = enabled
+      @value = value
+      @default = default
+    end
+
+    def enabled?
+      @enabled
+    end
+
+    alias is_default default
+
+    def <=>(other)
+      feature_name <=> other.feature_name
+    end
+
+    def [](key)
+      to_h[key]
+    end
+
+    def to_h
+      {
+        feature_id: feature_id,
+        feature_name: feature_name,
+        value: value,
+        enabled: enabled,
+        default: default
+      }
+    end
+
+    class << self
+      def from_feature_state_model(feature_state_model, identity_id)
+        new(
+          enabled: feature_state_model.enabled,
+          value: feature_state_model.get_value(identity_id),
+          feature_name: feature_state_model.feature.name,
+          feature_id: feature_state_model.feature.id
+        )
+      end
+
+      def from_api(json_flag_data)
+        new(
+          enabled: json_flag_data[:enabled],
+          value: json_flag_data[:feature_state_value] || json_flag_data[:value],
+          feature_name: json_flag_data.dig(:feature, :name),
+          feature_id: json_flag_data.dig(:feature, :id)
+        )
+      end
+    end
+  end
+end

data/lib/flagsmith/sdk/models/flags/collection.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Flagsmith
+  module Flags
+    class NotFound < StandardError; end
+
+    # Flag Collection
+    class Collection
+      include Enumerable
+
+      attr_reader :flags, :default_flag_handler, :analytics_processor
+
+      def initialize(flags = {}, analytics_processor: nil, default_flag_handler: nil)
+        @flags = flags
+        @default_flag_handler = default_flag_handler
+        @analytics_processor = analytics_processor
+      end
+
+      def each(&block)
+        flags.each { |item| block&.call(item) || item }
+      end
+
+      def to_a
+        @flags.values || []
+      end
+      alias all_flags to_a
+
+      # Check whether a given feature is enabled.
+      # :param feature_name: the name of the feature to check if enabled.
+      # :return: Boolean representing the enabled state of a given feature.
+      # :raises FlagsmithClientError: if feature doesn't exist
+      def feature_enabled?(feature_name)
+        get_flag(feature_name).enabled?
+      end
+      alias is_feature_enabled feature_enabled?
+
+      # Get the value of a particular feature.
+      # :param feature_name: the name of the feature to retrieve the value of.
+      # :return: the value of the given feature.
+      # :raises FlagsmithClientError: if feature doesn't exist
+      def feature_value(feature_name)
+        get_flag(feature_name).value
+      end
+      alias get_feature_value feature_value
+
+      # Get a specific flag given the feature name.
+      # :param feature_name: the name of the feature to retrieve the flag for.
+      # :return: BaseFlag object.
+      # :raises FlagsmithClientError: if feature doesn't exist
+      def get_flag(feature_name)
+        key = Flagsmith::Flags::Collection.normalize_key(feature_name)
+        flag = flags.fetch(key)
+        @analytics_processor.track_feature(flag.feature_id) if @analytics_processor && flag.feature_id
+        flag
+      rescue KeyError
+        return @default_flag_handler.call(feature_name) if @default_flag_handler
+
+        raise Flagsmith::Flags::NotFound,
+              "Feature does not exist: #{key}, implement default_flag_handler to handle this case."
+      end
+
+      def [](key)
+        key.is_a?(Integer) ? to_a[key] : get_flag(key)
+      end
+
+      def length
+        to_a.length
+      end
+
+      def inspect
+        "<##{self.class}:#{object_id.to_s(8)} flags=#{@flags}>"
+      end
+
+      class << self
+        def from_api(json_data, **args)
+          to_flag_object = lambda { |json_flag, acc|
+            acc[normalize_key(json_flag.dig(:feature, :name))] =
+              Flagsmith::Flag.from_api(json_flag)
+          }
+
+          new(
+            json_data.each_with_object({}, &to_flag_object),
+            **args
+          )
+        end
+
+        def from_feature_state_models(feature_states, identity_id: nil, **args)
+          to_flag_object = lambda { |feature_state, acc|
+            acc[normalize_key(feature_state.feature.name)] =
+              Flagsmith::Flag.from_feature_state_model(feature_state, identity_id)
+          }
+
+          new(
+            feature_states.each_with_object({}, &to_flag_object),
+            **args
+          )
+        end
+
+        def normalize_key(key)
+          key.to_s.downcase
+        end
+      end
+    end
+  end
+end

data/lib/flagsmith/sdk/pooling_manager.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'intervals'
+
+module Flagsmith
+  # Manager to asynchronously fetch the environment
+  class EnvironmentDataPollingManager
+    include Flagsmith::SDK::Intervals
+
+    def initialize(main, refresh_interval_seconds)
+      @main = main
+      @refresh_interval_seconds = refresh_interval_seconds
+    end
+
+    def start
+      update_environment = lambda {
+        stop
+        @interval = set_interval(@refresh_interval_seconds) { @main.update_environment }
+      }
+
+      # TODO: this call should be awaited for getIdentityFlags/getEnvironmentFlags when enableLocalEvaluation is true
+      update_environment.call
+    end
+
+    def stop
+      return unless @interval
+
+      clear_interval(@interval)
+    end
+  end
+end

data/lib/flagsmith/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Flagsmith
+  VERSION = '3.0.0'
+end