statsig 1.10.0 → 1.20.0

data/lib/statsig.rb

@@ -1,59 +1,268 @@
+# typed: true
+
 require 'statsig_driver'
+require 'sorbet-runtime'
+require 'statsig_errors'
 
 module Statsig
+  extend T::Sig
+
+  sig { params(secret_key: String, options: T.any(StatsigOptions, NilClass), error_callback: T.any(Method, Proc, NilClass)).void }
+  ##
+  # Initializes the Statsig SDK.
+  #
+  # @param secret_key The server SDK key copied from console.statsig.com
+  # @param options The StatsigOptions object used to configure the SDK
+  # @param error_callback A callback function, called if the initialize network call fails
   def self.initialize(secret_key, options = nil, error_callback = nil)
     unless @shared_instance.nil?
       puts 'Statsig already initialized.'
+      @shared_instance.maybe_restart_background_threads
       return @shared_instance
     end
 
+    self.bind_sorbet_loggers(options)
+
     @shared_instance = StatsigDriver.new(secret_key, options, error_callback)
   end
 
+  sig { params(user: StatsigUser, gate_name: String).returns(T::Boolean) }
+  ##
+  # Gets the boolean result of a gate, evaluated against the given user. An exposure event will automatically be logged for the gate.
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param gate_name The name of the gate being checked
   def self.check_gate(user, gate_name)
     ensure_initialized
     @shared_instance&.check_gate(user, gate_name)
   end
 
+  sig { params(user: StatsigUser, gate_name: String).returns(T::Boolean) }
+  ##
+  # Gets the boolean result of a gate, evaluated against the given user.
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param gate_name The name of the gate being checked
+  def self.check_gate_with_exposure_logging_disabled(user, gate_name)
+    ensure_initialized
+    @shared_instance&.check_gate(user, gate_name, StatsigDriver::CheckGateOptions.new(log_exposure: false))
+  end
+
+  sig { params(user: StatsigUser, gate_name: String).void }
+  ##
+  # Logs an exposure event for the gate
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param gate_name The name of the gate being checked
+  def self.manually_log_gate_exposure(user, gate_name)
+    ensure_initialized
+    @shared_instance&.manually_log_gate_exposure(user, gate_name)
+  end
+
+  sig { params(user: StatsigUser, dynamic_config_name: String).returns(DynamicConfig) }
+  ##
+  # Get the values of a dynamic config, evaluated against the given user. An exposure event will automatically be logged for the dynamic config.
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param dynamic_config_name The name of the dynamic config
   def self.get_config(user, dynamic_config_name)
     ensure_initialized
     @shared_instance&.get_config(user, dynamic_config_name)
   end
 
+  sig { params(user: StatsigUser, dynamic_config_name: String).returns(DynamicConfig) }
+  ##
+  # Get the values of a dynamic config, evaluated against the given user.
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param dynamic_config_name The name of the dynamic config
+  def self.get_config_with_exposure_logging_disabled(user, dynamic_config_name)
+    ensure_initialized
+    @shared_instance&.get_config(user, dynamic_config_name, StatsigDriver::GetConfigOptions.new(log_exposure: false))
+  end
+
+  sig { params(user: StatsigUser, dynamic_config: String).void }
+  ##
+  # Logs an exposure event for the dynamic config
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param dynamic_config_name The name of the dynamic config
+  def self.manually_log_config_exposure(user, dynamic_config)
+    ensure_initialized
+    @shared_instance&.manually_log_config_exposure(user, dynamic_config)
+  end
+
+  sig { params(user: StatsigUser, experiment_name: String).returns(DynamicConfig) }
+  ##
+  # Get the values of an experiment, evaluated against the given user. An exposure event will automatically be logged for the experiment.
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param experiment_name The name of the experiment
   def self.get_experiment(user, experiment_name)
     ensure_initialized
     @shared_instance&.get_experiment(user, experiment_name)
   end
 
+  sig { params(user: StatsigUser, experiment_name: String).returns(DynamicConfig) }
+  ##
+  # Get the values of an experiment, evaluated against the given user.
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param experiment_name The name of the experiment
+  def self.get_experiment_with_exposure_logging_disabled(user, experiment_name)
+    ensure_initialized
+    @shared_instance&.get_experiment(user, experiment_name, StatsigDriver::GetExperimentOptions.new(log_exposure: false))
+  end
+
+  sig { params(user: StatsigUser, experiment_name: String).void }
+  ##
+  # Logs an exposure event for the experiment
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param experiment_name The name of the experiment
+  def self.manually_log_experiment_exposure(user, experiment_name)
+    ensure_initialized
+    @shared_instance&.manually_log_config_exposure(user, experiment_name)
+  end
+
+  sig { params(user: StatsigUser, layer_name: String).returns(Layer) }
+  ##
+  # Get the values of a layer, evaluated against the given user.
+  # Exposure events will be fired when get or get_typed is called on the resulting Layer class.
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param layer_name The name of the layer
   def self.get_layer(user, layer_name)
     ensure_initialized
     @shared_instance&.get_layer(user, layer_name)
   end
 
+  sig { params(user: StatsigUser, layer_name: String).returns(Layer) }
+  ##
+  # Get the values of a layer, evaluated against the given user.
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param layer_name The name of the layer
+  def self.get_layer_with_exposure_logging_disabled(user, layer_name)
+    ensure_initialized
+    @shared_instance&.get_layer(user, layer_name, StatsigDriver::GetLayerOptions.new(log_exposure: false))
+  end
+
+  sig { params(user: StatsigUser, layer_name: String, parameter_name: String).returns(Layer) }
+  ##
+  # Logs an exposure event for the parameter in the given layer
+  #
+  # @param user A StatsigUser object used for the evaluation
+  # @param layer_name The name of the layer
+  # @param parameter_name The name of the parameter in the layer
+  def self.manually_log_layer_parameter_exposure(user, layer_name, parameter_name)
+    ensure_initialized
+    @shared_instance&.manually_log_layer_parameter_exposure(user, layer_name, parameter_name)
+  end
+
+  sig { params(user: StatsigUser,
+               event_name: String,
+               value: T.any(String, Integer, Float, NilClass),
+               metadata: T.any(T::Hash[String, T.untyped], NilClass)).void }
+  ##
+  # Logs an event to Statsig with the provided values.
+  #
+  # @param user A StatsigUser object to be included in the log
+  # @param event_name The name given to the event
+  # @param value A top level value for the event
+  # @param metadata Any extra values to be logged
   def self.log_event(user, event_name, value = nil, metadata = nil)
     ensure_initialized
     @shared_instance&.log_event(user, event_name, value, metadata)
   end
 
+  sig { void }
+  ##
+  # Stops all Statsig activity and flushes any pending events.
   def self.shutdown
-    unless @shared_instance.nil?
+    if defined? @shared_instance and !@shared_instance.nil?
       @shared_instance.shutdown
     end
     @shared_instance = nil
   end
 
+  sig { params(gate_name: String, gate_value: T::Boolean).void }
+  ##
+  # Sets a value to be returned for the given gate instead of the actual evaluated value.
+  #
+  # @param gate_name The name of the gate to be overridden
+  # @param gate_value The value that will be returned
+  def self.override_gate(gate_name, gate_value)
+    ensure_initialized
+    @shared_instance&.override_gate(gate_name, gate_value)
+  end
+
+  sig { params(config_name: String, config_value: Hash).void }
+  ##
+  # Sets a value to be returned for the given dynamic config/experiment instead of the actual evaluated value.
+  #
+  # @param config_name The name of the dynamic config or experiment to be overridden
+  # @param config_value The value that will be returned
+  def self.override_config(config_name, config_value)
+    ensure_initialized
+    @shared_instance&.override_config(config_name, config_value)
+  end
+
+  sig { params(user: StatsigUser).returns(T.any(T::Hash[String, T.untyped], NilClass)) }
+  ##
+  # Gets all evaluated values for the given user.
+  # These values can then be given to a Statsig Client SDK via bootstrapping.
+  #
+  # @param user A StatsigUser object used for the evaluation
+  #
+  # @note See Ruby Documentation: https://docs.statsig.com/server/rubySDK)
+  def self.get_client_initialize_response(user)
+    ensure_initialized
+    @shared_instance&.get_client_initialize_response(user)
+  end
+
+  sig { returns(T::Hash[String, String]) }
+  ##
+  # Internal Statsig metadata for this SDK
   def self.get_statsig_metadata
     {
       'sdkType' => 'ruby-server',
-      'sdkVersion' => '1.10.0',
+      'sdkVersion' => '1.20.0',
     }
   end
 
   private
 
   def self.ensure_initialized
-    if @shared_instance.nil?
-      raise 'Must call initialize first.'
+    if not defined? @shared_instance or @shared_instance.nil?
+      raise Statsig::UninitializedError.new
     end
   end
+
+  sig { params(options: T.any(StatsigOptions, NilClass)).void }
+
+  def self.bind_sorbet_loggers(options)
+    if options&.disable_sorbet_logging_handlers == true
+      return
+    end
+
+    T::Configuration.call_validation_error_handler = lambda do |signature, opts|
+      puts "[Type Error] " + opts[:pretty_message]
+    end
+
+    T::Configuration.inline_type_error_handler = lambda do |error, opts|
+      puts "[Type Error] " + error.message
+    end
+
+    T::Configuration.sig_builder_error_handler = lambda do |error, location|
+      puts "[Type Error] " + error.message
+    end
+
+    T::Configuration.sig_validation_error_handler = lambda do |error, opts|
+      puts "[Type Error] " + error.message
+    end
+
+    return
+  end
+
 end

data/lib/statsig_driver.rb

@@ -1,116 +1,236 @@
+# typed: true
+
 require 'config_result'
 require 'evaluator'
 require 'network'
+require 'statsig_errors'
 require 'statsig_event'
 require 'statsig_logger'
 require 'statsig_options'
 require 'statsig_user'
 require 'spec_store'
 require 'dynamic_config'
+require 'error_boundary'
 require 'layer'
+require 'sorbet-runtime'
+require 'diagnostics'
 
 class StatsigDriver
+  extend T::Sig
+
+  sig { params(secret_key: String, options: T.any(StatsigOptions, NilClass), error_callback: T.any(Method, Proc, NilClass)).void }
+
   def initialize(secret_key, options = nil, error_callback = nil)
-    super()
-    if !secret_key.is_a?(String) || !secret_key.start_with?('secret-')
-      raise 'Invalid secret key provided. Provide your project secret key from the Statsig console'
+    unless secret_key.start_with?('secret-')
+      raise Statsig::ValueError.new('Invalid secret key provided. Provide your project secret key from the Statsig console')
     end
+
     if !options.nil? && !options.instance_of?(StatsigOptions)
-      raise 'Invalid options provided. Either provide a valid StatsigOptions object or nil'
+      raise Statsig::ValueError.new('Invalid options provided. Either provide a valid StatsigOptions object or nil')
     end
 
-    @options = options || StatsigOptions.new
-    @shutdown = false
-    @secret_key = secret_key
-    @net = Statsig::Network.new(secret_key, @options.api_url_base)
-    @logger = Statsig::StatsigLogger.new(@net)
-    @evaluator = Statsig::Evaluator.new(@net, @options, error_callback)
+    @err_boundary = Statsig::ErrorBoundary.new(secret_key)
+    @err_boundary.capture(-> {
+      @init_diagnostics = Statsig::Diagnostics.new("initialize")
+      @init_diagnostics.mark("overall", "start")
+      @options = options || StatsigOptions.new
+      @shutdown = false
+      @secret_key = secret_key
+      @net = Statsig::Network.new(secret_key, @options.api_url_base, @options.local_mode)
+      @logger = Statsig::StatsigLogger.new(@net, @options)
+      @evaluator = Statsig::Evaluator.new(@net, @options, error_callback, @init_diagnostics)
+      @init_diagnostics.mark("overall", "end")
+
+      log_init_diagnostics
+    })
+  end
+
+  class CheckGateOptions < T::Struct
+    prop :log_exposure, T::Boolean, default: true
+  end
+
+  sig { params(user: StatsigUser, gate_name: String, options: CheckGateOptions).returns(T::Boolean) }
+
+  def check_gate(user, gate_name, options = CheckGateOptions.new)
+    @err_boundary.capture(-> {
+      user = verify_inputs(user, gate_name, "gate_name")
+
+      res = @evaluator.check_gate(user, gate_name)
+      if res.nil?
+        res = Statsig::ConfigResult.new(gate_name)
+      end
+
+      if res == $fetch_from_server
+        res = check_gate_fallback(user, gate_name)
+        # exposure logged by the server
+      else
+        if options.log_exposure
+          @logger.log_gate_exposure(user, res.name, res.gate_value, res.rule_id, res.secondary_exposures, res.evaluation_details)
+        end
+      end
+
+      res.gate_value
+    }, -> { false })
+
   end
 
-  def check_gate(user, gate_name)
-    user = verify_inputs(user, gate_name, "gate_name")
+  sig { params(user: StatsigUser, gate_name: String).void }
 
+  def manually_log_gate_exposure(user, gate_name)
     res = @evaluator.check_gate(user, gate_name)
-    if res.nil?
-      res = Statsig::ConfigResult.new(gate_name)
-    end
+    context = {'is_manual_exposure' => true}
+    @logger.log_gate_exposure(user, gate_name, res.gate_value, res.rule_id, res.secondary_exposures, res.evaluation_details, context)
+  end
 
-    if res == $fetch_from_server
-      res = check_gate_fallback(user, gate_name)
-      # exposure logged by the server
-    else
-      @logger.log_gate_exposure(user, res.name, res.gate_value, res.rule_id, res.secondary_exposures)
-    end
+  class GetConfigOptions < T::Struct
+    prop :log_exposure, T::Boolean, default: true
+  end
+
+  sig { params(user: StatsigUser, dynamic_config_name: String, options: GetConfigOptions).returns(DynamicConfig) }
 
-    res.gate_value
+  def get_config(user, dynamic_config_name, options = GetConfigOptions.new)
+    @err_boundary.capture(-> {
+      user = verify_inputs(user, dynamic_config_name, "dynamic_config_name")
+      get_config_impl(user, dynamic_config_name, options)
+    }, -> { DynamicConfig.new(dynamic_config_name) })
   end
 
-  def get_config(user, dynamic_config_name)
-    user = verify_inputs(user, dynamic_config_name, "dynamic_config_name")
-    get_config_impl(user, dynamic_config_name)
+  class GetExperimentOptions < T::Struct
+    prop :log_exposure, T::Boolean, default: true
   end
 
-  def get_experiment(user, experiment_name)
-    user = verify_inputs(user, experiment_name, "experiment_name")
-    get_config_impl(user, experiment_name)
+  sig { params(user: StatsigUser, experiment_name: String, options: GetExperimentOptions).returns(DynamicConfig) }
+
+  def get_experiment(user, experiment_name, options = GetExperimentOptions.new)
+    @err_boundary.capture(-> {
+      user = verify_inputs(user, experiment_name, "experiment_name")
+      get_config_impl(user, experiment_name, options)
+    }, -> { DynamicConfig.new(experiment_name) })
   end
 
-  def get_layer(user, layer_name)
-    user = verify_inputs(user, layer_name, "layer_name")
+  sig { params(user: StatsigUser, config_name: String).void }
 
-    res = @evaluator.get_layer(user, layer_name)
-    if res.nil?
-      res = Statsig::ConfigResult.new(layer_name)
-    end
+  def manually_log_config_exposure(user, config_name)
+    res = @evaluator.get_config(user, config_name)
+    context = {'is_manual_exposure' => true}
+    @logger.log_config_exposure(user, res.name, res.rule_id, res.secondary_exposures, res.evaluation_details, context)
+  end
 
-    if res == $fetch_from_server
-      if res.config_delegate.empty?
-        return Layer.new(layer_name)
+  class GetLayerOptions < T::Struct
+    prop :log_exposure, T::Boolean, default: true
+  end
+
+  sig { params(user: StatsigUser, layer_name: String, options: GetLayerOptions).returns(Layer) }
+
+  def get_layer(user, layer_name, options = GetLayerOptions.new)
+    @err_boundary.capture(-> {
+      user = verify_inputs(user, layer_name, "layer_name")
+
+      res = @evaluator.get_layer(user, layer_name)
+      if res.nil?
+        res = Statsig::ConfigResult.new(layer_name)
       end
-      res = get_config_fallback(user, res.config_delegate)
-      # exposure logged by the server
-    end
 
-    Layer.new(res.name, res.json_value, res.rule_id, lambda { |layer, parameter_name|
-      @logger.log_layer_exposure(user, layer, parameter_name, res)
+      if res == $fetch_from_server
+        if res.config_delegate.empty?
+          return Layer.new(layer_name)
+        end
+        res = get_config_fallback(user, res.config_delegate)
+        # exposure logged by the server
+      end
+      
+      exposure_log_func = options.log_exposure ? lambda { |layer, parameter_name|
+        @logger.log_layer_exposure(user, layer, parameter_name, res)
+      } : nil
+      Layer.new(res.name, res.json_value, res.rule_id, exposure_log_func)
+    }, -> {
+      Layer.new(layer_name)
     })
   end
 
+  sig { params(user: StatsigUser, layer_name: String, parameter_name: String).void }
+
+  def manually_log_layer_parameter_exposure(user, layer_name, parameter_name)
+    res = @evaluator.get_layer(user, layer_name)
+    layer = Layer.new(layer_name, res.json_value, res.rule_id)
+    context = {'is_manual_exposure' => true}
+    @logger.log_layer_exposure(user, layer, parameter_name, res, context)
+  end
+
   def log_event(user, event_name, value = nil, metadata = nil)
-    if !user.nil? && !user.instance_of?(StatsigUser)
-      raise 'Must provide a valid StatsigUser or nil'
-    end
-    check_shutdown
+    @err_boundary.capture(-> {
+      if !user.nil? && !user.instance_of?(StatsigUser)
+        raise Statsig::ValueError.new('Must provide a valid StatsigUser or nil')
+      end
+      check_shutdown
 
-    user = normalize_user(user)
+      user = normalize_user(user)
 
-    event = StatsigEvent.new(event_name)
-    event.user = user
-    event.value = value
-    event.metadata = metadata
-    event.statsig_metadata = Statsig.get_statsig_metadata
-    @logger.log_event(event)
+      event = StatsigEvent.new(event_name)
+      event.user = user
+      event.value = value
+      event.metadata = metadata
+      event.statsig_metadata = Statsig.get_statsig_metadata
+      @logger.log_event(event)
+    })
   end
 
   def shutdown
-    @shutdown = true
-    @logger.flush(true)
-    @evaluator.shutdown
+    @err_boundary.capture(-> {
+      @shutdown = true
+      @logger.shutdown
+      @evaluator.shutdown
+    })
+  end
+
+  def override_gate(gate_name, gate_value)
+    @err_boundary.capture(-> {
+      @evaluator.override_gate(gate_name, gate_value)
+    })
+  end
+
+  def override_config(config_name, config_value)
+    @err_boundary.capture(-> {
+      @evaluator.override_config(config_name, config_value)
+    })
+  end
+
+  # @param [StatsigUser] user
+  # @return [Hash]
+  def get_client_initialize_response(user)
+    @err_boundary.capture(-> {
+      normalize_user(user)
+      @evaluator.get_client_initialize_response(user)
+    }, -> { nil })
+  end
+
+  def maybe_restart_background_threads
+    if @options.local_mode
+      return
+    end
+
+    @err_boundary.capture(-> {
+      @evaluator.maybe_restart_background_threads
+      @logger.maybe_restart_background_threads
+    })
   end
 
   private
 
+  sig { params(user: StatsigUser, config_name: String, variable_name: String).returns(StatsigUser) }
+
   def verify_inputs(user, config_name, variable_name)
     validate_user(user)
     if !config_name.is_a?(String) || config_name.empty?
-      raise "Invalid #{variable_name} provided"
+      raise Statsig::ValueError.new("Invalid #{variable_name} provided")
     end
 
     check_shutdown
+    maybe_restart_background_threads
     normalize_user(user)
   end
 
-  def get_config_impl(user, config_name)
+  def get_config_impl(user, config_name, options)
     res = @evaluator.get_config(user, config_name)
     if res.nil?
       res = Statsig::ConfigResult.new(config_name)
@@ -120,7 +240,9 @@ class StatsigDriver
       res = get_config_fallback(user, config_name)
       # exposure logged by the server
     else
-      @logger.log_config_exposure(user, res.name, res.rule_id, res.secondary_exposures)
+      if options.log_exposure
+        @logger.log_config_exposure(user, res.name, res.rule_id, res.secondary_exposures, res.evaluation_details)
+      end
     end
 
     DynamicConfig.new(res.name, res.json_value, res.rule_id)
@@ -132,9 +254,9 @@ class StatsigDriver
       (
         # user_id is nil and custom_ids is not a hash with entries
         !user.user_id.is_a?(String) &&
-        (!user.custom_ids.is_a?(Hash) || user.custom_ids.size == 0)
+          (!user.custom_ids.is_a?(Hash) || user.custom_ids.size == 0)
       )
-      raise 'Must provide a valid StatsigUser with a user_id or at least a custom ID. See https://docs.statsig.com/messages/serverRequiredUserID/ for more details.'
+      raise Statsig::ValueError.new('Must provide a valid StatsigUser with a user_id or at least a custom ID. See https://docs.statsig.com/messages/serverRequiredUserID/ for more details.')
     end
   end
 
@@ -180,4 +302,12 @@ class StatsigDriver
       network_result['rule_id'],
     )
   end
-end
+
+  def log_init_diagnostics
+    if @options.disable_diagnostics_logging
+      return
+    end
+
+    @logger.log_diagnostics_event(@init_diagnostics)
+  end
+end

data/lib/statsig_errors.rb

@@ -0,0 +1,11 @@
+module Statsig
+  class UninitializedError < StandardError
+    def initialize(msg="Must call initialize first.")
+      super
+    end
+  end
+
+  class ValueError < StandardError
+
+  end
+end

data/lib/statsig_event.rb

@@ -1,3 +1,4 @@
+# typed: true
 class StatsigEvent
   attr_accessor :value
   attr_accessor :metadata
@@ -7,7 +8,11 @@ class StatsigEvent
 
   def initialize(event_name)
     @event_name = event_name
-    @time = Time.now.to_f * 1000
+    @value = nil
+    @metadata = nil
+    @secondary_exposures = nil
+    @user = nil
+    @time = (Time.now.to_f * 1000).to_i
   end
 
   def user=(value)