amplitude-experiment 1.0.0.beta.4 → 1.0.0.beta.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 653e4953eeea7497bb43f1e76c144c8fe7360dcc53c7aa3f9c63e3b28e1052ee
-  data.tar.gz: 9b8ea31ccb93aebd815019f6dab4f739ea49b96177800dc6a39b9f1907f64ad0
+  metadata.gz: 3c1c474415a95c82dd30feb5730a517d3df489f39ac6b307583a66d20b844fc3
+  data.tar.gz: f215b72c1dc816aa205c68d3b9fac5b4685ca4ee90cacc035f6f2106bd1cf9eb
 SHA512:
-  metadata.gz: 4a1b221d66a28d1cc53c20c5eba088baa3a180ec628603d8801ed759ef893b6a74162abb8396ed3bac2f97f51aa45e7536adedc4509f1d719c2495ff2e129df1
-  data.tar.gz: 1757f94f26bf55016c8604ee065ae4d24d95b431ac7a27687190fe8e138d6ac402d94248eba90f9c23d94fd918179d28da8ffc02c9c03004e5bdeaafa8e24db1
+  metadata.gz: e55171f2998fcebf9f9a49a785445e1731b0b86a0d98a5b0ff8111702cb7a5c03df8c3e641492acaa30bb45b3750fc237c79d6a7ee964424cd8ebb5061180835
+  data.tar.gz: 3ec5bfd97ed595841541074b9f7079e94a7b0452a8b53ecdd722dfd18956ed40f12d26503c04d6a9a84ae2ec2c9d4119dea0420b4566bb591f959296710df080

data/README.md

@@ -25,7 +25,7 @@ gem install amplitude-experiment --pre
 ```
 
 
-## Quick Start
+## Remote Evaluation Quick Start
 ```ruby
 require 'amplitude-experiment'
 
@@ -33,10 +33,10 @@ require 'amplitude-experiment'
 apiKey = 'YOUR-API-KEY'
 
 # (2) Initialize the experiment client
-experiment = Experiment.init(api_key)
+experiment = AmplitudeExperiment.initialize_remote(api_key)
 
 # (3) Fetch variants for a user
-user = Experiment::User.new(user_id: 'user@company.com', device_id: 'abcezas123', user_properties: {'premium' => true})
+user = AmplitudeExperiment::User.new(user_id: 'user@company.com', device_id: 'abcezas123', user_properties: {'premium' => true})
 
 # (4) Lookup a flag's variant
 # 
@@ -64,6 +64,33 @@ unless variant.nil?
 end
 ```
 
+## Local Evaluation Quick Start
+
+```ruby
+require 'amplitude-experiment'
+
+# (1) Get your deployment's API key
+apiKey = 'YOUR-API-KEY'
+
+# (2) Initialize the experiment client
+experiment = AmplitudeExperiment.initialize_local(api_key)
+
+# (3) Start the local evaluation client
+experiment.start
+
+# (4) Evaluate a user
+user = AmplitudeExperiment::User.new(user_id: 'user@company.com', device_id: 'abcezas123', user_properties: {'premium' => true})
+variants = experiment.evaluate(user)
+variant = variants['YOUR-FLAG-KEY']
+unless variant.nil?
+  if variant.value == 'on'
+    # Flag is on
+  else
+    # Flag is off
+  end
+end
+```
+
 ## More Information
 Please visit our :100:[Developer Center](https://www.docs.developers.amplitude.com/experiment/sdks/ruby-sdk/) for more instructions on using our the SDK.
 

data/lib/amplitude-experiment.rb

@@ -1 +1,17 @@
-require 'experiment'
+require 'experiment/version'
+require 'experiment/persistent_http_client'
+require 'experiment/remote/config'
+require 'experiment/cookie'
+require 'experiment/user'
+require 'experiment/variant'
+require 'experiment/factory'
+require 'experiment/remote/client'
+require 'experiment/local/client'
+require 'experiment/local/config'
+require 'experiment/local/cache'
+require 'experiment/local/fetcher'
+require 'experiment/local/poller'
+
+# Amplitude Experiment Module
+module AmplitudeExperiment
+end

data/lib/experiment/cookie.rb

@@ -1,6 +1,6 @@
 require 'base64'
 
-module Experiment
+module AmplitudeExperiment
   # This class provides utility functions for parsing and handling identity from Amplitude cookies.
   class AmplitudeCookie
     # Get the cookie name that Amplitude sets for the provided

data/lib/experiment/factory.rb

@@ -1,6 +1,7 @@
 # Provides factory methods for storing singleton instance of Client
-module Experiment
-  @instances = {}
+module AmplitudeExperiment
+  @local_instance = {}
+  @remote_instance = {}
   @default_instance = '$default_instance'
 
   # Initializes a singleton Client. This method returns a default singleton instance, subsequent calls to
@@ -8,8 +9,23 @@ module Experiment
   #
   # @param [String] api_key The environment API Key
   # @param [Config] config Optional Config.
-  def self.init(api_key, config = nil)
-    @instances.store(@default_instance, Client.new(api_key, config)) unless @instances.key?(@default_instance)
-    @instances.fetch(@default_instance)
+  def self.initialize_remote(api_key, config = nil)
+    unless @local_instance.key?(@default_instance)
+      @local_instance.store(@default_instance, RemoteEvaluationClient.new(api_key, config))
+    end
+    @local_instance.fetch(@default_instance)
+  end
+
+  # Initializes a local evaluation Client. A local evaluation client can evaluate local flags or experiments for a
+  # user without requiring a remote call to the amplitude evaluation server. In order to best leverage local
+  # evaluation, all flags, and experiments being evaluated server side should be configured as local.
+  #
+  # @param [String] api_key The environment API Key
+  # @param [Config] config Optional Config.
+  def self.initialize_local(api_key, config = nil)
+    unless @remote_instance.key?(@default_instance)
+      @remote_instance.store(@default_instance, LocalEvaluationClient.new(api_key, config))
+    end
+    @remote_instance.fetch(@default_instance)
   end
 end

data/lib/experiment/local/cache.rb

@@ -0,0 +1,53 @@
+require 'uri'
+require 'logger'
+
+module AmplitudeExperiment
+  # InMemoryFlagConfigCache
+  # The place to store the flag configs fetched from the server
+  class InMemoryFlagConfigCache
+    attr_accessor :cache
+
+    def initialize(flag_configs = {})
+      @semaphore = Mutex.new
+      @cache = flag_configs
+    end
+
+    def get(flag_key)
+      @semaphore.synchronize do
+        @cache.fetch(flag_key, nil)
+      end
+    end
+
+    def caches
+      @semaphore.synchronize do
+        @cache
+      end
+    end
+
+    def put(flag_key, flag_config)
+      @semaphore.synchronize do
+        @cache.store(flag_key, flag_config.clone)
+      end
+    end
+
+    def put_all(flag_configs)
+      @semaphore.synchronize do
+        flag_configs.each do |key, value|
+          @cache.store(key, value.clone) if value
+        end
+      end
+    end
+
+    def delete(flag_key)
+      @semaphore.synchronize do
+        @cache.delete(flag_key)
+      end
+    end
+
+    def clear
+      @semaphore.synchronize do
+        @cache = {}
+      end
+    end
+  end
+end

data/lib/experiment/local/client.rb

@@ -0,0 +1,84 @@
+require 'uri'
+require 'logger'
+require 'experiment/local/evaluation/evaluation'
+
+module AmplitudeExperiment
+  # Main client for fetching variant data.
+  class LocalEvaluationClient
+    # Creates a new Experiment Client instance.
+    #
+    # @param [String] api_key The environment API Key
+    # @param [LocalEvaluationConfig] config The config object
+    def initialize(api_key, config = nil)
+      @api_key = api_key
+      @config = config || LocalEvaluationConfig.new
+      @cache = InMemoryFlagConfigCache.new(@config.bootstrap)
+      @logger = Logger.new($stdout)
+      @logger.level = if @config.debug
+                        Logger::DEBUG
+                      else
+                        Logger::INFO
+                      end
+      @fetcher = LocalEvaluationFetcher.new(api_key, @config.debug, @config.server_url)
+      @poller = FlagConfigPoller.new(@fetcher, @cache, @config.debug)
+
+      raise ArgumentError, 'Experiment API key is empty' if @api_key.nil? || @api_key.empty?
+    end
+
+    # Locally evaluates flag variants for a user.
+    #
+    # @param [User] user The user to evaluate
+    # @param [String[]] flag_keys The flags to evaluate with the user. If empty, all flags from the flag cache are evaluated
+    #
+    # @return [Hash[String, Variant]] The evaluated variants
+    def evaluate(user, flag_keys = [])
+      flag_configs = []
+      if flag_keys.empty?
+        @cache.cache.each do |_, value|
+          flag_configs.push(value)
+        end
+      else
+        flag_configs = get_flag_configs(flag_keys)
+      end
+      flag_configs_str = flag_configs.to_json
+      user_str = user.to_json
+      @logger.debug("[Experiment] Evaluate: User: #{user_str} - Rules: #{flag_configs_str}") if @config.debug
+      result_json = evaluation(flag_configs_str, user_str)
+      @logger.debug(`[Experiment] evaluate - result: #{variants}`) if @config.debug
+      result = JSON.parse(result_json)
+      variants = {}
+      result.each do |key, value|
+        next if value['isDefaultVariant']
+
+        variant_key = value['variant']['key']
+        variant_payload = value['variant']['payload']
+        variants.store(key, Variant.new(variant_key, variant_payload))
+      end
+      variants
+    end
+
+    # Fetch initial flag configurations and start polling for updates.
+    # You must call this function to begin polling for flag config updates.
+    def start
+      @poller.start
+    end
+
+    # Stop polling for flag configurations. Close resource like connection pool with client
+    def stop
+      @poller.stop
+    end
+
+    private
+
+    def get_flag_configs(flag_keys = [])
+      return @cache.cache if flag_keys.empty?
+
+      flag_configs = []
+      flag_keys.each do |key|
+        flag_config = @cache.get(key)
+        flag_configs.push(flag_config) if flag_config
+      end
+      flag_configs
+    end
+  end
+end

data/lib/experiment/local/config.rb

@@ -0,0 +1,35 @@
+module AmplitudeExperiment
+  # LocalEvaluationConfig
+  class LocalEvaluationConfig
+    # Default server url
+    DEFAULT_SERVER_URL = 'https://api.lab.amplitude.com'.freeze
+
+    # Set to true to log some extra information to the console.
+    # @return [Boolean] the value of debug
+    attr_accessor :debug
+
+    # The server endpoint from which to request variants.
+    # @return [String] the value of server url
+    attr_accessor :server_url
+
+    # The server endpoint from which to request variants.
+    # @return [Hash] the value of bootstrap
+    attr_accessor :bootstrap
+
+    # The server endpoint from which to request variants.
+    # @return [long] the value of flag config polling interval in million seconds
+    attr_accessor :flag_config_polling_interval_millis
+
+    # @param [Boolean] debug Set to true to log some extra information to the console.
+    # @param [String] server_url The server endpoint from which to request variants.
+    # @param [Hash] bootstrap The value of bootstrap.
+    # @param [long] flag_config_polling_interval_millis The value of flag config polling interval in million seconds.
+    def initialize(server_url = DEFAULT_SERVER_URL, bootstrap = {},
+                   flag_config_polling_interval_millis = 30_000, debug: false)
+      @debug = debug || false
+      @server_url = server_url
+      @bootstrap = bootstrap
+      @flag_config_polling_interval_millis = flag_config_polling_interval_millis
+    end
+  end
+end

data/lib/experiment/local/evaluation/evaluation.rb

@@ -0,0 +1,48 @@
+# rubocop:disable all
+require 'ffi'
+
+# The evaluation wrapper
+module EvaluationInterop
+  extend FFI::Library
+  host_os = RbConfig::CONFIG['host_os']
+  cpu = RbConfig::CONFIG['host_cpu']
+  evaluation_dir = File.dirname(__FILE__)
+  ffi_lib ["#{evaluation_dir}/lib/macosX64/libevaluation_interop.dylib"] if host_os =~ /darwin|mac os/ && cpu =~ /x86_64/
+  ffi_lib ["#{evaluation_dir}/lib/macosArm64/libevaluation_interop.dylib"] if host_os =~ /darwin|mac os/ && cpu =~ /arm64/
+  ffi_lib ["#{evaluation_dir}/lib/linuxX64/libevaluation_interop.so"] if host_os =~ /linux/ && cpu =~ /x86_64/
+  ffi_lib ["#{evaluation_dir}/lib/linuxArm64/libevaluation_interop.so"] if host_os =~ /linux/ && cpu =~ /arm64/
+
+  class Root < FFI::Struct
+    layout :evaluate, callback([:string, :string], :pointer)
+  end
+
+  class Kotlin < FFI::Struct
+    layout :root, Root
+  end
+
+  class Libevaluation_interop_ExportedSymbols < FFI::Struct
+    layout :DisposeStablePointer, callback([:pointer], :void),
+           :DisposeString, callback([:string], :void),
+           :IsInstance, callback([:pointer, :string], :pointer),
+           :createNullableByte, callback([:string], :pointer),
+           :createNullableShort, callback([:pointer], :pointer),
+           :createNullableInt, callback([:pointer], :pointer),
+           :createNullableLong, callback([:pointer], :pointer),
+           :createNullableFloat, callback([:pointer], :pointer),
+           :createNullableDouble, callback([:pointer], :pointer),
+           :createNullableChar, callback([:pointer], :pointer),
+           :createNullableBoolean, callback([:pointer], :pointer),
+           :createNullableUnit, callback([], :pointer),
+           :kotlin, Kotlin
+  end
+
+  attach_function :libevaluation_interop_symbols, [], Libevaluation_interop_ExportedSymbols.by_ref
+end
+
+def evaluation(rule_json, user_json)
+  lib = EvaluationInterop.libevaluation_interop_symbols()
+  fn = lib[:kotlin][:root][:evaluate]
+  evaluation_result = fn.call(rule_json, user_json)
+  evaluation_result.read_string
+end
+# rubocop:disable all

data/lib/experiment/local/fetcher.rb

@@ -0,0 +1,45 @@
+module AmplitudeExperiment
+  # LocalEvaluationFetcher
+  # Fetch local evaluation mode flag configs from the Experiment API server.
+  # These flag configs can be used to perform local evaluation.
+  class LocalEvaluationFetcher
+    FLAG_CONFIG_TIMEOUT = 5000
+
+    def initialize(api_key, debug, server_url = 'https://api.lab.amplitude.com')
+      @api_key = api_key
+      @uri = "#{server_url}/sdk/rules?eval_mode=local"
+      @debug = debug
+      @http =  PersistentHttpClient.get(@uri, { read_timeout: FLAG_CONFIG_TIMEOUT })
+    end
+
+    # Fetch local evaluation mode flag configs from the Experiment API server.
+    # These flag configs can be used to perform local evaluation.
+    #
+    # @return [Hash] The flag configs
+    def fetch
+      # fetch flag_configs
+      headers = {
+        'Authorization' => "Api-Key #{@api_key}",
+        'Content-Type' => 'application/json;charset=utf-8'
+      }
+      request = Net::HTTP::Get.new(@uri, headers)
+      response = @http.request(request)
+      raise `flagConfigs - received error response: #{response.status}: #{response.body}` unless response.is_a?(Net::HTTPOK)
+
+      flag_configs = parse(response.body)
+      @logger.debug("[Experiment] Fetch flag configs: #{request.body}") if @debug
+      flag_configs
+    end
+
+    private
+
+    def parse(flag_configs_str)
+      flag_config_obj = {}
+      flag_configs_array = JSON.parse(flag_configs_str)
+      flag_configs_array.each do |flag_config|
+        flag_config_obj.store(flag_config['flagKey'], flag_config) if flag_config.key?('flagKey')
+      end
+      flag_config_obj
+    end
+  end
+end

data/lib/experiment/local/poller.rb

@@ -0,0 +1,48 @@
+module AmplitudeExperiment
+  # FlagConfigPoller
+  # update the flag_config cache value
+  class FlagConfigPoller
+    FLAG_CONFIG_POLLING_INTERVAL_MILLIS = 30_000
+
+    def initialize(fetcher, cache, debug, poll_interval_millis: FLAG_CONFIG_POLLING_INTERVAL_MILLIS)
+      @fetcher = fetcher
+      @cache = cache
+      @poll_interval_millis = poll_interval_millis
+      @logger = Logger.new($stdout)
+      @debug = debug
+      @poller_thread = nil
+      @is_running = false
+    end
+
+    # Fetch initial flag configurations and start polling for updates.
+    # You must call this function to begin polling for flag config updates.
+    # Calling this function while the poller is already running does nothing.
+    def start
+      return if @is_running
+
+      @logger.debug('[Experiment] poller - start') if @debug
+      run
+    end
+
+    # Stop polling for flag configurations.
+    # Calling this function while the poller is not running will do nothing.
+    def stop
+      @poller_thread&.exit
+      @is_running = false
+      @poller_thread = nil
+    end
+
+    private
+
+    def run
+      @is_running = true
+      flag_configs = @fetcher.fetch
+      @cache.clear
+      @cache.put_all(flag_configs)
+      @poller_thread = Thread.new do
+        sleep @poll_interval_millis
+        run
+      end
+    end
+  end
+end

data/lib/experiment/persistent_http_client.rb

@@ -1,4 +1,4 @@
-module Experiment
+module AmplitudeExperiment
   # Persist Http Client to reuse connection and reduce IO
   class PersistentHttpClient
     DEFAULT_OPTIONS = { read_timeout: 80 }.freeze

data/lib/experiment/{client.rb → remote/client.rb}

@@ -3,16 +3,16 @@ require 'json'
 require 'uri'
 require 'logger'
 
-module Experiment
+module AmplitudeExperiment
   # Main client for fetching variant data.
-  class Client
+  class RemoteEvaluationClient
     # Creates a new Experiment Client instance.
     #
     # @param [String] api_key The environment API Key
     # @param [Config] config
     def initialize(api_key, config = nil)
       @api_key = api_key
-      @config = config || Config.new
+      @config = config || RemoteEvaluationConfig.new
       @logger = Logger.new($stdout)
       @logger.level = if @config.debug
                         Logger::DEBUG
@@ -40,6 +40,7 @@ module Experiment
     #
     # This method will automatically retry if configured (default).
     # @param [User] user
+    # @yield [User, Hash] callback block takes user object and variants hash
     def fetch_async(user, &callback)
       Thread.new do
         variants = fetch_internal(user)
@@ -138,7 +139,7 @@ module Experiment
     # @return [User, Hash] user with library context
     def add_context(user)
       user = {} if user.nil?
-      user.library = "experiment-ruby-server/#{VERSION}" if user.library.nil?
+      user.library = "experiment-ruby-server/#{VERSION}"
       user
     end
   end

data/lib/experiment/{config.rb → remote/config.rb}

@@ -1,6 +1,6 @@
-module Experiment
+module AmplitudeExperiment
   # Configuration
-  class Config
+  class RemoteEvaluationConfig
     # Default server url
     DEFAULT_SERVER_URL = 'https://api.lab.amplitude.com'.freeze
 

data/lib/experiment/user.rb

@@ -1,4 +1,4 @@
-module Experiment
+module AmplitudeExperiment
   # Defines a user context for evaluation.
   # `device_id` and `user_id` are used for identity resolution.
   # All other predefined fields and user properties are used for

data/lib/experiment/variant.rb

@@ -1,4 +1,4 @@
-module Experiment
+module AmplitudeExperiment
   # Variant
   class Variant
     # The value of the variant determined by the flag configuration.

data/lib/experiment/version.rb

@@ -1,3 +1,3 @@
-module Experiment
-  VERSION = '1.0.0.beta.4'.freeze
+module AmplitudeExperiment
+  VERSION = '1.0.0.beta.7'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: amplitude-experiment
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta.4
+  version: 1.0.0.beta.7
 platform: ruby
 authors:
 - Amplitude
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-06-30 00:00:00.000000000 Z
+date: 2022-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -108,6 +108,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.15.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.15.5
 description: Amplitude Experiment Ruby Server SDK
 email:
 - sdk@amplitude.com
@@ -119,12 +133,17 @@ files:
 - Gemfile
 - README.md
 - lib/amplitude-experiment.rb
-- lib/experiment.rb
-- lib/experiment/client.rb
-- lib/experiment/config.rb
 - lib/experiment/cookie.rb
 - lib/experiment/factory.rb
+- lib/experiment/local/cache.rb
+- lib/experiment/local/client.rb
+- lib/experiment/local/config.rb
+- lib/experiment/local/evaluation/evaluation.rb
+- lib/experiment/local/fetcher.rb
+- lib/experiment/local/poller.rb
 - lib/experiment/persistent_http_client.rb
+- lib/experiment/remote/client.rb
+- lib/experiment/remote/config.rb
 - lib/experiment/user.rb
 - lib/experiment/variant.rb
 - lib/experiment/version.rb

data/lib/experiment.rb

@@ -1,12 +0,0 @@
-require 'experiment/version'
-require 'experiment/config'
-require 'experiment/cookie'
-require 'experiment/user'
-require 'experiment/variant'
-require 'experiment/factory'
-require 'experiment/persistent_http_client'
-require 'experiment/client'
-
-# Amplitude Experiment Module
-module Experiment
-end