featbit-server-sdk 0.1.0

data/lib/featbit/evaluator.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+require "json"
+require "set"
+require "timeout"
+
+module FeatBit
+  class Evaluator
+    REGEXP_TIMEOUT = 0.05
+    NATIVE_REGEXP_TIMEOUT_SUPPORTED = Regexp.respond_to?(:timeout)
+
+    REASONS = {
+      client_not_ready: "client not ready",
+      flag_not_found: "flag not found",
+      error: "error in evaluation",
+      user_not_specified: "user not specified",
+      wrong_type: "wrong type",
+      flag_off: "flag off",
+      target_match: "target match",
+      rule_match: "rule match",
+      fallthrough: "fall through all rules"
+    }.freeze
+
+    def initialize(flag_getter:, segment_getter:, logger: nil)
+      @flag_getter = flag_getter
+      @segment_getter = segment_getter
+      @logger = logger
+    end
+
+    def evaluate(flag_key, user, default_value)
+      return error_detail(flag_key, default_value, :user_not_specified) unless user&.valid?
+
+      flag = @flag_getter.call(flag_key.to_s)
+      return error_detail(flag_key, default_value, :flag_not_found) unless flag
+
+      variation_id, reason, send_to_experiment = select_variation(flag, user, Set.new)
+      raise "no variation matched" if variation_id.to_s.empty?
+
+      raw_value = fetch(fetch(flag, "variationMap", {}), variation_id)
+      raise "variation value not found" if raw_value.nil?
+
+      value = cast(raw_value, fetch(flag, "variationType"))
+      EvaluationDetail.new(
+        value: value,
+        reason: REASONS.fetch(reason),
+        variation_id: variation_id,
+        flag_key: fetch(flag, "key", flag_key),
+        flag_name: fetch(flag, "name"),
+        send_to_experiment: send_to_experiment
+      )
+    rescue StandardError => e
+      @logger&.error("FeatBit evaluation failed: #{e.message}")
+      error_detail(flag_key, default_value, :error, e.message)
+    end
+
+    private
+
+    def select_variation(flag, user, visited_segments)
+      return [fetch(flag, "disabledVariationId"), :flag_off, false] unless fetch(flag, "isEnabled", false)
+
+      Array(fetch(flag, "targetUsers", [])).each do |target|
+        if Array(fetch(target, "keyIds", [])).map(&:to_s).include?(user.key)
+          return [fetch(target, "variationId"), :target_match, fetch(flag, "exptIncludeAllTargets", false) == true]
+        end
+      end
+
+      Array(fetch(flag, "rules", [])).each do |rule|
+        next unless Array(fetch(rule, "conditions", [])).all? do |condition|
+          condition_matches?(user, condition, visited_segments)
+        end
+
+        variation_id, send_to_experiment = rollout_variation(flag, rule, user)
+        return [variation_id, :rule_match, send_to_experiment] if variation_id
+      end
+
+      variation_id, send_to_experiment = rollout_variation(flag, fetch(flag, "fallthrough", {}), user)
+      [variation_id, :fallthrough, send_to_experiment]
+    end
+
+    def rollout_variation(flag, rollout, user)
+      dispatch_key = fetch(rollout, "dispatchKey") || "keyId"
+      dispatch_value = user[dispatch_key].to_s
+      bucket_key = "#{fetch(flag, 'key')}#{dispatch_value}"
+      Array(fetch(rollout, "variations", [])).each do |variation|
+        range = Array(fetch(variation, "rollout", []))
+        next unless in_bucket?(bucket_key, range)
+
+        return [fetch(variation, "id"), send_to_experiment?(flag, rollout, variation, bucket_key, range)]
+      end
+      [nil, false]
+    end
+
+    def send_to_experiment?(flag, rollout, variation, bucket_key, range)
+      return true if fetch(flag, "exptIncludeAllTargets", false)
+      return false unless fetch(rollout, "includedInExpt", false)
+
+      span = range[1].to_f - range[0].to_f
+      experiment_rollout = fetch(variation, "exptRollout", 0).to_f
+      return false unless span.positive? && experiment_rollout.positive?
+
+      upper_bound = [experiment_rollout / span, 1.0].min
+      in_bucket?("expt#{bucket_key}", [0, upper_bound])
+    rescue StandardError
+      false
+    end
+
+    def in_bucket?(key, range)
+      return false unless range.length == 2
+      return true if range[0].to_f.zero? && range[1].to_f >= 1.0
+
+      signed = Digest::MD5.digest(key.to_s).byteslice(0, 4).unpack1("l<")
+      percentage = (signed / -2_147_483_648.0).abs
+      percentage >= range[0].to_f && percentage < range[1].to_f
+    rescue StandardError
+      false
+    end
+
+    def condition_matches?(user, condition, visited_segments = Set.new)
+      property = fetch(condition, "property")
+      operation = fetch(condition, "op") || property
+      actual = user[property]
+      expected = fetch(condition, "value")
+      actual_number = numeric_value(actual)
+      expected_number = numeric_value(expected)
+
+      case operation
+      when "BiggerEqualThan" then actual_number && expected_number && actual_number >= expected_number
+      when "BiggerThan" then actual_number && expected_number && actual_number > expected_number
+      when "LessEqualThan" then actual_number && expected_number && actual_number <= expected_number
+      when "LessThan" then actual_number && expected_number && actual_number < expected_number
+      when "Equal" then !actual.nil? && !expected.nil? && actual.to_s == expected.to_s
+      when "NotEqual" then actual.nil? || expected.nil? || actual.to_s != expected.to_s
+      when "Contains" then !actual.nil? && !expected.nil? && actual.to_s.include?(expected.to_s)
+      when "NotContain" then actual.nil? || expected.nil? || !actual.to_s.include?(expected.to_s)
+      when "IsOneOf" then json_array(expected).map(&:to_s).include?(actual.to_s)
+      when "NotOneOf" then !json_array(expected).map(&:to_s).include?(actual.to_s)
+      when "StartsWith" then !actual.nil? && actual.to_s.start_with?(expected.to_s)
+      when "EndsWith" then !actual.nil? && actual.to_s.end_with?(expected.to_s)
+      when "IsTrue" then actual == true || actual.to_s.casecmp("true").zero?
+      when "IsFalse" then actual == false || actual.to_s.casecmp("false").zero?
+      when "MatchRegex" then !actual.nil? && regex_match(expected, actual) == true
+      when "NotMatchRegex" then actual.nil? || regex_match(expected, actual) == false
+      when "User is in segment" then segment_match?(user, expected, visited_segments)
+      when "User is not in segment" then !segment_match?(user, expected, visited_segments)
+      else false
+      end
+    rescue StandardError
+      false
+    end
+
+    def regex_match(pattern, value)
+      if NATIVE_REGEXP_TIMEOUT_SUPPORTED
+        Regexp.new(pattern.to_s, timeout: REGEXP_TIMEOUT).match?(value.to_s)
+      else
+        Timeout.timeout(REGEXP_TIMEOUT) { Regexp.new(pattern.to_s).match?(value.to_s) }
+      end
+    rescue StandardError
+      nil
+    end
+
+    def segment_match?(user, serialized_ids, visited_segments)
+      json_array(serialized_ids).any? do |segment_id|
+        normalized_id = segment_id.to_s
+        next false if visited_segments.include?(normalized_id)
+
+        segment = @segment_getter.call(normalized_id)
+        next false unless segment
+        next false if Array(fetch(segment, "excluded", [])).map(&:to_s).include?(user.key)
+        next true if Array(fetch(segment, "included", [])).map(&:to_s).include?(user.key)
+
+        nested_visited = visited_segments | [normalized_id]
+        Array(fetch(segment, "rules", [])).any? do |rule|
+          Array(fetch(rule, "conditions", [])).all? do |condition|
+            condition_matches?(user, condition, nested_visited)
+          end
+        end
+      end
+    end
+
+    def cast(value, type)
+      case type.to_s.downcase
+      when "boolean" then cast_boolean(value)
+      when "number" then numeric_cast(value)
+      when "json" then value.is_a?(String) ? JSON.parse(value) : value
+      else value.to_s
+      end
+    end
+
+    def cast_boolean(value)
+      return value if [true, false].include?(value)
+      return true if value.is_a?(String) && value.casecmp("true").zero?
+      return false if value.is_a?(String) && value.casecmp("false").zero?
+
+      raise "invalid boolean variation"
+    end
+
+    def numeric_cast(value)
+      number = Float(value)
+      number.finite? && number == number.to_i ? number.to_i : number
+    end
+
+    def numeric_value(value)
+      Float(value).round(5)
+    rescue StandardError
+      nil
+    end
+
+    def json_array(value)
+      parsed = value.is_a?(String) ? JSON.parse(value) : value
+      parsed.is_a?(Array) ? parsed : []
+    rescue StandardError
+      []
+    end
+
+    def error_detail(flag_key, default_value, kind, message = nil)
+      EvaluationDetail.new(
+        value: default_value,
+        reason: REASONS.fetch(kind),
+        flag_key: flag_key,
+        error_kind: kind,
+        error_message: message
+      )
+    end
+
+    def fetch(hash, key, default = nil)
+      hash.is_a?(Hash) ? hash.fetch(key.to_s, hash.fetch(key.to_sym, default)) : default
+    end
+  end
+end

data/lib/featbit/event_processor.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "timeout"
+require "uri"
+
+module FeatBit
+  class EventProcessor
+    class DeliveryRejected < StandardError; end
+
+    FLUSH = "__flush__"
+    STOP = "__stop__"
+    CONTROL_TIMEOUT = 5.0
+
+    def initialize(options, sender: nil)
+      @options = options
+      @sender = sender || method(:post_batch)
+      @queue = SizedQueue.new(options.events_capacity)
+      @control_queue = Queue.new
+      @dropped_events = 0
+      @drop_mutex = Mutex.new
+      @state_mutex = Mutex.new
+      @close_mutex = Mutex.new
+      @closed = false
+      @close_result = nil
+      @thread = Thread.new { run }
+      @thread.name = "featbit-event-processor" if @thread.respond_to?(:name=)
+    rescue StandardError => e
+      options.logger&.error("FeatBit event processor failed to start: #{e.message}")
+      @closed = true
+    end
+
+    def enqueue(event)
+      return false if event.nil?
+
+      @state_mutex.synchronize do
+        return false if @closed
+
+        @queue.push(event, true)
+        true
+      end
+    rescue ThreadError
+      @drop_mutex.synchronize { @dropped_events += 1 }
+      false
+    rescue StandardError => e
+      @options.logger&.warn("FeatBit event enqueue failed: #{e.message}")
+      false
+    end
+
+    def flush
+      ack = Queue.new
+      @state_mutex.synchronize do
+        return false if @closed
+
+        @control_queue << { type: FLUSH, ack: ack }
+      end
+
+      Timeout.timeout(CONTROL_TIMEOUT) { ack.pop } != false
+    rescue StandardError => e
+      @options.logger&.warn("FeatBit event flush failed: #{e.message}")
+      false
+    end
+
+    def close
+      @close_mutex.synchronize do
+        return @close_result unless @close_result.nil?
+
+        ack = Queue.new
+        worker_alive = @thread&.alive?
+        @state_mutex.synchronize do
+          @closed = true
+          @control_queue << { type: STOP, ack: ack } if worker_alive
+        end
+        return @close_result = true unless worker_alive
+
+        delivered = Timeout.timeout(CONTROL_TIMEOUT) { ack.pop } != false
+        @thread&.join(CONTROL_TIMEOUT)
+        @close_result = delivered && !@thread&.alive?
+      end
+    rescue StandardError => e
+      @options.logger&.warn("FeatBit event processor close failed: #{e.message}")
+      false
+    end
+
+    def dropped_events
+      @drop_mutex.synchronize { @dropped_events }
+    rescue StandardError
+      0
+    end
+
+    private
+
+    def run
+      batch = []
+      deadline = monotonic_time + @options.events_flush_interval
+      loop do
+        event = pop_with_timeout([deadline - monotonic_time, 0].max)
+        if control?(event, STOP)
+          drain_events(batch)
+          delivered = send_batch(batch)
+          batch.clear
+          event[:ack].push(delivered)
+          break
+        elsif control?(event, FLUSH)
+          drain_events(batch)
+          delivered = send_batch(batch)
+          batch.clear
+          event[:ack].push(delivered)
+          deadline = monotonic_time + @options.events_flush_interval
+        elsif event
+          batch << event
+          if batch.length >= @options.events_batch_size
+            send_batch(batch)
+            batch.clear
+            deadline = monotonic_time + @options.events_flush_interval
+          end
+        elsif monotonic_time >= deadline
+          send_batch(batch)
+          batch.clear
+          deadline = monotonic_time + @options.events_flush_interval
+        end
+      end
+    rescue StandardError => e
+      @options.logger&.error("FeatBit event processor stopped unexpectedly: #{e.message}")
+    ensure
+      mark_closed
+    end
+
+    def pop_with_timeout(timeout)
+      deadline = monotonic_time + timeout
+      loop do
+        return @control_queue.pop(true)
+      rescue ThreadError
+        begin
+          return @queue.pop(true)
+        rescue ThreadError
+          return nil if monotonic_time >= deadline
+
+          sleep([deadline - monotonic_time, 0.01].min)
+        end
+      end
+    end
+
+    def drain_events(batch)
+      loop do
+        batch << @queue.pop(true)
+      rescue ThreadError
+        break
+      end
+      batch
+    end
+
+    def control?(event, type)
+      event.is_a?(Hash) && event[:type] == type
+    end
+
+    def send_batch(batch)
+      return true if batch.empty?
+
+      delivered = true
+      batch.each_slice(@options.events_batch_size) do |slice|
+        delivered = false unless send_slice(slice)
+      end
+      delivered
+    end
+
+    def send_slice(batch)
+      attempts = 0
+
+      begin
+        attempts += 1
+        delivered = @sender.call(batch.dup)
+        raise "sender rejected batch" if delivered == false
+
+        true
+      rescue DeliveryRejected
+        raise
+      rescue StandardError
+        retry if attempts < 3
+
+        raise
+      end
+    rescue StandardError => e
+      @options.logger&.warn("FeatBit event delivery failed: #{e.message}")
+      false
+    end
+
+    def post_batch(batch)
+      uri = URI.parse(@options.events_uri)
+      request = Net::HTTP::Post.new(uri)
+      request["Authorization"] = @options.env_secret
+      request["User-Agent"] = "featbit-ruby-server-sdk/#{FeatBit::VERSION}"
+      request["Content-Type"] = "application/json"
+      request.body = JSON.generate(batch)
+      response = Net::HTTP.start(
+        uri.host, uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: @options.connect_timeout,
+        read_timeout: @options.read_timeout
+      ) { |http| http.request(request) }
+      unless response.is_a?(Net::HTTPSuccess)
+        message = response.body.to_s.gsub(/\s+/, " ").strip[0, 200]
+        raise DeliveryRejected, ["HTTP #{response.code}", message].reject(&:empty?).join(": ")
+      end
+
+      true
+    end
+
+    def mark_closed
+      @state_mutex.synchronize { @closed = true }
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+
+  class NullEventProcessor
+    def enqueue(_event) = false
+    def flush = true
+    def close = true
+    def dropped_events = 0
+  end
+end

data/lib/featbit/options.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "logger"
+require "uri"
+
+module FeatBit
+  class Options
+    DEFAULT_STREAMING_URL = "wss://app-eval.featbit.co"
+    DEFAULT_EVENT_URL = "https://app-eval.featbit.co"
+
+    attr_reader :env_secret, :streaming_url, :event_url, :start_wait,
+                :offline, :bootstrap, :disable_events, :logger,
+                :events_capacity, :events_flush_interval, :events_batch_size,
+                :connect_timeout, :read_timeout, :reconnect_delay,
+                :data_store, :synchronizer_factory, :event_processor_factory
+
+    def initialize(env_secret: "", streaming_url: DEFAULT_STREAMING_URL,
+                   event_url: DEFAULT_EVENT_URL, start_wait: 5.0, offline: false,
+                   bootstrap: nil, disable_events: false, logger: nil,
+                   events_capacity: 10_000, events_flush_interval: 1.0,
+                   events_batch_size: 50, connect_timeout: 5.0,
+                   read_timeout: 10.0, reconnect_delay: 1.0,
+                   data_store: nil, synchronizer_factory: nil,
+                   event_processor_factory: nil)
+      @env_secret = env_secret.to_s
+      @streaming_url = normalize_url(streaming_url)
+      @event_url = normalize_url(event_url)
+      @start_wait = positive_number(start_wait, 5.0)
+      @offline = offline == true
+      @bootstrap = bootstrap
+      @disable_events = disable_events == true
+      @logger = logger || Logger.new($stderr, level: Logger::WARN)
+      @events_capacity = positive_integer(events_capacity, 10_000)
+      @events_flush_interval = positive_number(events_flush_interval, 1.0)
+      @events_batch_size = positive_integer(events_batch_size, 50)
+      @connect_timeout = positive_number(connect_timeout, 5.0)
+      @read_timeout = positive_number(read_timeout, 10.0)
+      @reconnect_delay = positive_number(reconnect_delay, 1.0)
+      @data_store = data_store
+      @synchronizer_factory = synchronizer_factory
+      @event_processor_factory = event_processor_factory
+      freeze
+    rescue StandardError => e
+      warn("FeatBit options error: #{e.message}")
+      @env_secret = ""
+      @streaming_url = DEFAULT_STREAMING_URL
+      @event_url = DEFAULT_EVENT_URL
+      @start_wait = 5.0
+      @offline = true
+      @bootstrap = nil
+      @disable_events = true
+      @logger = Logger.new($stderr, level: Logger::WARN)
+      @events_capacity = 10_000
+      @events_flush_interval = 1.0
+      @events_batch_size = 50
+      @connect_timeout = 5.0
+      @read_timeout = 10.0
+      @reconnect_delay = 1.0
+      freeze
+    end
+
+    def streaming_uri
+      append_path(streaming_url, "/streaming")
+    end
+
+    def events_uri
+      append_path(event_url, "/api/public/insight/track")
+    end
+
+    def valid?
+      return true if offline
+
+      !env_secret.empty? && valid_uri?(streaming_uri, %w[ws wss]) && valid_uri?(events_uri, %w[http https])
+    rescue StandardError
+      false
+    end
+
+    private
+
+    def normalize_url(value)
+      value.to_s.sub(%r{/+\z}, "")
+    end
+
+    def append_path(base, path)
+      base.end_with?(path) ? base : "#{base}#{path}"
+    end
+
+    def valid_uri?(value, schemes)
+      uri = URI.parse(value)
+      schemes.include?(uri.scheme) && !uri.host.to_s.empty?
+    end
+
+    def positive_number(value, fallback)
+      number = Float(value)
+      number.positive? ? number : fallback
+    rescue StandardError
+      fallback
+    end
+
+    def positive_integer(value, fallback)
+      number = Integer(value)
+      number.positive? ? number : fallback
+    rescue StandardError
+      fallback
+    end
+  end
+end

data/lib/featbit/status.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module FeatBit
+  module Status
+    STARTING = :starting
+    READY = :ready
+    INTERRUPTED = :interrupted
+    OFFLINE = :offline
+    FAILED = :failed
+    CLOSED = :closed
+  end
+
+  class StatusProvider
+    def initialize(initial = Status::STARTING, logger: nil)
+      @status = initial
+      @message = nil
+      @listeners = {}
+      @next_listener_id = 0
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @logger = logger
+    end
+
+    def status
+      @mutex.synchronize { @status }
+    end
+
+    def message
+      @mutex.synchronize { @message }
+    end
+
+    def ready?
+      status == Status::READY
+    end
+
+    def wait_until_ready(timeout = 5.0)
+      deadline = monotonic_time + timeout.to_f
+      @mutex.synchronize do
+        until @status == Status::READY
+          return false if [Status::FAILED, Status::CLOSED].include?(@status)
+
+          remaining = deadline - monotonic_time
+          return false unless remaining.positive?
+
+          @condition.wait(@mutex, remaining)
+        end
+      end
+      true
+    rescue StandardError
+      false
+    end
+
+    def add_listener(callable = nil, &block)
+      listener = callable || block
+      return nil unless listener.respond_to?(:call)
+
+      @mutex.synchronize do
+        @next_listener_id += 1
+        @listeners[@next_listener_id] = listener
+        @next_listener_id
+      end
+    rescue StandardError
+      nil
+    end
+
+    def remove_listener(id)
+      @mutex.synchronize { !@listeners.delete(id).nil? }
+    rescue StandardError
+      false
+    end
+
+    def update(new_status, message: nil)
+      listeners = @mutex.synchronize do
+        changed = @status != new_status || @message != message
+        @status = new_status
+        @message = message
+        @condition.broadcast
+        changed ? @listeners.values.dup : []
+      end
+      listeners.each do |listener|
+        listener.call(new_status, message)
+      rescue StandardError => e
+        safe_log(:warn, "FeatBit status listener failed: #{e.message}")
+      end
+      true
+    rescue StandardError => e
+      safe_log(:warn, "FeatBit status update failed: #{e.message}")
+      false
+    end
+
+    private
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def safe_log(level, message)
+      @logger&.public_send(level, message)
+    rescue StandardError
+      nil
+    end
+  end
+end