statsig 1.10.0 → 1.20.0

data/lib/statsig_logger.rb

@@ -1,50 +1,69 @@
+# typed: true
 require 'statsig_event'
+require 'concurrent-ruby'
 
 $gate_exposure_event = 'statsig::gate_exposure'
 $config_exposure_event = 'statsig::config_exposure'
 $layer_exposure_event = 'statsig::layer_exposure'
+$diagnostics_event = 'statsig::diagnostics'
 
 module Statsig
   class StatsigLogger
-    def initialize(network)
+    def initialize(network, options)
       @network = network
       @events = []
+      @options = options
+
+      @logging_pool = Concurrent::ThreadPoolExecutor.new(
+        min_threads: [2, Concurrent.processor_count].min,
+        max_threads: [2, Concurrent.processor_count].max,
+        # max jobs pending before we start dropping
+        max_queue:   [2, Concurrent.processor_count].max * 5,
+        fallback_policy: :discard,
+      )
+
       @background_flush = periodic_flush
     end
 
     def log_event(event)
       @events.push(event)
-      if @events.length >= 1000
-        flush
+      if @events.length >= @options.logging_max_buffer_size
+        flush_async
       end
     end
 
-    def log_gate_exposure(user, gate_name, value, rule_id, secondary_exposures)
+    def log_gate_exposure(user, gate_name, value, rule_id, secondary_exposures, eval_details, context = nil)
       event = StatsigEvent.new($gate_exposure_event)
       event.user = user
       event.metadata = {
         'gate' => gate_name,
         'gateValue' => value.to_s,
-        'ruleID' => rule_id
+        'ruleID' => rule_id,
       }
       event.statsig_metadata = Statsig.get_statsig_metadata
       event.secondary_exposures = secondary_exposures.is_a?(Array) ? secondary_exposures : []
+
+      safe_add_eval_details(eval_details, event)
+      safe_add_exposure_context(context, event)
       log_event(event)
     end
 
-    def log_config_exposure(user, config_name, rule_id, secondary_exposures)
+    def log_config_exposure(user, config_name, rule_id, secondary_exposures, eval_details, context = nil)
       event = StatsigEvent.new($config_exposure_event)
       event.user = user
       event.metadata = {
         'config' => config_name,
-        'ruleID' => rule_id
+        'ruleID' => rule_id,
       }
       event.statsig_metadata = Statsig.get_statsig_metadata
       event.secondary_exposures = secondary_exposures.is_a?(Array) ? secondary_exposures : []
+
+      safe_add_eval_details(eval_details, event)
+      safe_add_exposure_context(context, event)
       log_event(event)
     end
 
-    def log_layer_exposure(user, layer, parameter_name, config_evaluation)
+    def log_layer_exposure(user, layer, parameter_name, config_evaluation, context = nil)
       exposures = config_evaluation.undelegated_sec_exps
       allocated_experiment = ''
       is_explicit = (config_evaluation.explicit_parameters&.include? parameter_name) || false
@@ -60,26 +79,46 @@ module Statsig
         'ruleID' => layer.rule_id,
         'allocatedExperiment' => allocated_experiment,
         'parameterName' => parameter_name,
-        'isExplicitParameter' => String(is_explicit)
+        'isExplicitParameter' => String(is_explicit),
       }
       event.statsig_metadata = Statsig.get_statsig_metadata
       event.secondary_exposures = exposures.is_a?(Array) ? exposures : []
+
+      safe_add_eval_details(config_evaluation.evaluation_details, event)
+      safe_add_exposure_context(context, event)
+      log_event(event)
+    end
+
+    def log_diagnostics_event(diagnostics, user = nil)
+      event = StatsigEvent.new($diagnostics_event)
+      event.user = user
+      event.metadata = diagnostics.serialize
       log_event(event)
     end
 
     def periodic_flush
       Thread.new do
         loop do
-          sleep 60
+          sleep @options.logging_interval_seconds
           flush
         end
       end
     end
 
-    def flush(closing = false)
-      if closing
-        @background_flush&.exit
+    def shutdown
+      @background_flush&.exit
+      @logging_pool.shutdown
+      @logging_pool.wait_for_termination(timeout = 3)
+      flush
+    end
+
+    def flush_async
+      @logging_pool.post do
+        flush
       end
+    end
+
+    def flush
       if @events.length == 0
         return
       end
@@ -89,5 +128,34 @@ module Statsig
 
       @network.post_logs(flush_events)
     end
+
+    def maybe_restart_background_threads
+      if @background_flush.nil? or !@background_flush.alive?
+        @background_flush = periodic_flush
+      end
+    end
+
+    private
+
+    def safe_add_eval_details(eval_details, event)
+      if eval_details.nil?
+        return
+      end
+
+      event.metadata['reason'] = eval_details.reason
+      event.metadata['configSyncTime'] = eval_details.config_sync_time
+      event.metadata['initTime'] = eval_details.init_time
+      event.metadata['serverTime'] = eval_details.server_time
+    end
+
+    def safe_add_exposure_context(context, event)
+      if context.nil?
+        return
+      end
+
+      if context['is_manual_exposure']
+        event.metadata['isManualExposure'] = 'true'
+      end
+    end
   end
 end

data/lib/statsig_options.rb

@@ -1,17 +1,124 @@
+# typed: true
+
+require 'sorbet-runtime'
+require_relative 'interfaces/data_store'
+
+##
+# Configuration options for the Statsig SDK.
 class StatsigOptions
-  attr_reader :environment
-  attr_reader :api_url_base
-  attr_reader :rulesets_sync_interval
-  attr_reader :idlists_sync_interval
+  extend T::Sig
+
+  sig { returns(T.any(T::Hash[String, String], NilClass)) }
+  # Hash you can use to set environment variables that apply to all of your users in
+  # the same session and will be used for targeting purposes.
+  # eg. { "tier" => "development" }
+  attr_accessor :environment
+
+  sig { returns(String) }
+  # The base url used to make network calls to Statsig.
+  # default: https://statsigapi.net/v1
+  attr_accessor :api_url_base
+
+  sig { returns(T.any(Float, Integer)) }
+  # The interval (in seconds) to poll for changes to your Statsig configuration
+  # default: 10s
+  attr_accessor :rulesets_sync_interval
+
+  sig { returns(T.any(Float, Integer)) }
+  # The interval (in seconds) to poll for changes to your id lists
+  # default: 60s
+  attr_accessor :idlists_sync_interval
+
+  sig { returns(T.any(Float, Integer)) }
+  # How often to flush logs to Statsig
+  # default: 60s
+  attr_accessor :logging_interval_seconds
+
+  sig { returns(Integer) }
+  # The maximum number of events to batch before flushing logs to the server
+  # default: 1000
+  attr_accessor :logging_max_buffer_size
+
+  sig { returns(T::Boolean) }
+  # Restricts the SDK to not issue any network requests and only respond with default values (or local overrides)
+  # default: false
+  attr_accessor :local_mode
+
+  sig { returns(T.any(String, NilClass)) }
+  # A string that represents all rules for all feature gates, dynamic configs and experiments.
+  # It can be provided to bootstrap the Statsig server SDK at initialization in case your server runs
+  # into network issue or Statsig is down temporarily.
+  attr_accessor :bootstrap_values
+
+  sig { returns(T.any(Method, Proc, NilClass)) }
+  # A callback function that will be called anytime the rulesets are updated.
+  attr_accessor :rules_updated_callback
+
+  sig { returns(T.any(Statsig::Interfaces::IDataStore, NilClass)) }
+  # A class that extends IDataStore. Can be used to provide values from a
+  # common data store (like Redis) to initialize the Statsig SDK.
+  attr_accessor :data_store
+
+  sig { returns(Integer) }
+  # The number of threads allocated to syncing IDLists.
+  # default: 3
+  attr_accessor :idlist_threadpool_size
+
+  sig { returns(T::Boolean) }
+  # Should diagnostics be logged. These include performance metrics for initialize.
+  # default: false
+  attr_accessor :disable_diagnostics_logging
+
+  sig { returns(T::Boolean) }
+  # Statsig utilizes Sorbet (https://sorbet.org) to ensure type safety of the SDK. This includes logging
+  # to console when errors are detected. You can disable this logging by setting this flag to true.
+  # default: false
+  attr_accessor :disable_sorbet_logging_handlers
+
+  sig do
+    params(
+      environment: T.any(T::Hash[String, String], NilClass),
+      api_url_base: String,
+      rulesets_sync_interval: T.any(Float, Integer),
+      idlists_sync_interval: T.any(Float, Integer),
+      logging_interval_seconds: T.any(Float, Integer),
+      logging_max_buffer_size: Integer,
+      local_mode: T::Boolean,
+      bootstrap_values: T.any(String, NilClass),
+      rules_updated_callback: T.any(Method, Proc, NilClass),
+      data_store: T.any(Statsig::Interfaces::IDataStore, NilClass),
+      idlist_threadpool_size: Integer,
+      disable_diagnostics_logging: T::Boolean,
+      disable_sorbet_logging_handlers: T::Boolean
+    ).void
+  end
 
   def initialize(
-    environment=nil,
-    api_url_base='https://statsigapi.net/v1',
+    environment = nil,
+    api_url_base = 'https://statsigapi.net/v1',
     rulesets_sync_interval: 10,
-    idlists_sync_interval: 60)
+    idlists_sync_interval: 60,
+    logging_interval_seconds: 60,
+    logging_max_buffer_size: 1000,
+    local_mode: false,
+    bootstrap_values: nil,
+    rules_updated_callback: nil,
+    data_store: nil,
+    idlist_threadpool_size: 3,
+    disable_diagnostics_logging: false,
+    disable_sorbet_logging_handlers: false)
     @environment = environment.is_a?(Hash) ? environment : nil
     @api_url_base = api_url_base
     @rulesets_sync_interval = rulesets_sync_interval
     @idlists_sync_interval = idlists_sync_interval
+    @logging_interval_seconds = logging_interval_seconds
+    @logging_max_buffer_size = [logging_max_buffer_size, 1000].min
+    @local_mode = local_mode
+    @bootstrap_values = bootstrap_values
+    @rules_updated_callback = rules_updated_callback
+    @data_store = data_store
+    @idlist_threadpool_size = idlist_threadpool_size
+    @disable_diagnostics_logging = disable_diagnostics_logging
+    @disable_sorbet_logging_handlers = disable_sorbet_logging_handlers
   end
 end

data/lib/statsig_user.rb

@@ -1,40 +1,78 @@
+# typed: true
+
+require 'sorbet-runtime'
+
+##
+#  The user object to be evaluated against your Statsig configurations (gates/experiments/dynamic configs).
 class StatsigUser
+  extend T::Sig
+
+  sig { returns(T.any(String, NilClass)) }
+  # An identifier for this user. Evaluated against the User ID criteria. (https://docs.statsig.com/feature-gates/conditions#userid)
   attr_accessor :user_id
+
+  sig { returns(T.any(String, NilClass)) }
+  # An identifier for this user. Evaluated against the Email criteria. (https://docs.statsig.com/feature-gates/conditions#email)
   attr_accessor :email
+
+  sig { returns(T.any(String, NilClass)) }
+  # An IP address associated with this user. Evaluated against the IP Address criteria. (https://docs.statsig.com/feature-gates/conditions#ip)
   attr_accessor :ip
+
+  sig { returns(T.any(String, NilClass)) }
+  # A user agent string associated with this user. Evaluated against Browser Version and Name (https://docs.statsig.com/feature-gates/conditions#browser-version)
   attr_accessor :user_agent
+
+  sig { returns(T.any(String, NilClass)) }
+  # The country code associated with this user (e.g New Zealand => NZ). Evaluated against the Country criteria. (https://docs.statsig.com/feature-gates/conditions#country)
   attr_accessor :country
+
+  sig { returns(T.any(String, NilClass)) }
+  # An locale for this user.
   attr_accessor :locale
+
+  sig { returns(T.any(String, NilClass)) }
+  # The current app version the user is interacting with. Evaluated against the App Version criteria. (https://docs.statsig.com/feature-gates/conditions#app-version)
   attr_accessor :app_version
+
+  sig { returns(T.any(T::Hash[String, String], NilClass)) }
+  # A Hash you can use to set environment variables that apply to this user. e.g. { "tier" => "development" }
   attr_accessor :statsig_environment
+
+  sig { returns(T.any(T::Hash[String, String], NilClass)) }
+  # Any Custom IDs to associated with the user. (See https://docs.statsig.com/guides/experiment-on-custom-id-types)
   attr_accessor :custom_ids
+
+  sig { returns(T.any(T::Hash[String, String], NilClass)) }
+  # Any value you wish to use in evaluation, but do not want logged with events, can be stored in this field.
   attr_accessor :private_attributes
 
+  sig { returns(T.any(T::Hash[String, T.untyped], NilClass)) }
+
   def custom
     @custom
   end
 
+  sig { params(value: T.any(T::Hash[String, T.untyped], NilClass)).void }
+  # Any custom fields for this user. Evaluated against the Custom criteria. (https://docs.statsig.com/feature-gates/conditions#custom)
   def custom=(value)
     @custom = value.is_a?(Hash) ? value : Hash.new
   end
 
+  sig { params(user_hash: T.any(T::Hash[T.any(String, Symbol), T.untyped], NilClass)).void }
+
   def initialize(user_hash)
-    @statsig_environment = Hash.new
-    if user_hash.is_a?(Hash)
-      @user_id = user_hash['userID'] || user_hash['user_id']
-      @user_id = @user_id.to_s unless @user_id.nil?
-      @email = user_hash['email']
-      @ip = user_hash['ip']
-      @user_agent = user_hash['userAgent'] || user_hash['user_agent']
-      @country = user_hash['country']
-      @locale = user_hash['locale']
-      @app_version = user_hash['appVersion'] || user_hash['app_version']
-      @custom = user_hash['custom'] if user_hash['custom'].is_a? Hash
-      @statsig_environment = user_hash['statsigEnvironment']
-      @private_attributes = user_hash['privateAttributes'] if user_hash['privateAttributes'].is_a? Hash
-      custom_ids = user_hash['customIDs'] || user_hash['custom_ids']
-      @custom_ids = custom_ids if custom_ids.is_a? Hash
-    end
+    @user_id = from_hash(user_hash, [:user_id, :userID], String)
+    @email = from_hash(user_hash, [:email], String)
+    @ip = from_hash(user_hash, [:ip], String)
+    @user_agent = from_hash(user_hash, [:user_agent, :userAgent], String)
+    @country = from_hash(user_hash, [:country], String)
+    @locale = from_hash(user_hash, [:locale], String)
+    @app_version = from_hash(user_hash, [:app_version, :appVersion], String)
+    @custom = from_hash(user_hash, [:custom], Hash)
+    @private_attributes = from_hash(user_hash, [:private_attributes, :privateAttributes], Hash)
+    @custom_ids = from_hash(user_hash, [:custom_ids, :customIDs], Hash)
+    @statsig_environment = from_hash(user_hash, [:statsig_environment, :statsigEnvironment], Hash)
   end
 
   def serialize(for_logging)
@@ -76,4 +114,29 @@ class StatsigUser
       'privateAttributes' => @private_attributes,
     }
   end
+
+  private
+
+  sig {
+    params(user_hash: T.any(T::Hash[T.any(String, Symbol), T.untyped], NilClass),
+           keys: T::Array[Symbol],
+           type: T.untyped)
+      .returns(T.untyped)
+  }
+  # Pulls fields from the user hash via Symbols and Strings
+  def from_hash(user_hash, keys, type)
+    if user_hash.nil?
+      return nil
+    end
+
+    keys.each do |key|
+      val = user_hash[key] || user_hash[key.to_s]
+      if not val.nil? and val.is_a? type
+        return val
+      end
+    end
+
+    nil
+  end
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: statsig
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.20.0
 platform: ruby
 authors:
 - Statsig, Inc
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-07-07 00:00:00.000000000 Z
+date: 2023-01-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +66,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.5.10461
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.5.10461
+- !ruby/object:Gem::Dependency
+  name: tapioca
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.27
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.27
 - !ruby/object:Gem::Dependency
   name: user_agent_parser
   requirement: !ruby/object:Gem::Requirement
@@ -102,34 +130,68 @@ dependencies:
         version: '6.0'
 - !ruby/object:Gem::Dependency
   name: ip3country
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.10461
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.10461
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '1.1'
 description: Statsig server SDK for feature gates and experimentation in Ruby
 email: support@statsig.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/client_initialize_helpers.rb
 - lib/config_result.rb
+- lib/diagnostics.rb
 - lib/dynamic_config.rb
+- lib/error_boundary.rb
+- lib/evaluation_details.rb
 - lib/evaluation_helpers.rb
 - lib/evaluator.rb
 - lib/id_list.rb
+- lib/interfaces/data_store.rb
 - lib/layer.rb
 - lib/network.rb
 - lib/spec_store.rb
 - lib/statsig.rb
 - lib/statsig_driver.rb
+- lib/statsig_errors.rb
 - lib/statsig_event.rb
 - lib/statsig_logger.rb
 - lib/statsig_options.rb
@@ -146,14 +208,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
 summary: Statsig server SDK for Ruby