featbit-server-sdk 0.1.0

data/lib/featbit/client.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FeatBit
+  class Client
+    attr_reader :options, :status_provider, :event_processor, :data_store
+
+    def initialize(options = Options.new)
+      @options = options.is_a?(Options) ? options : Options.new(offline: true)
+      @data_store = @options.data_store || InMemoryDataStore.new
+      initial_status = @options.offline ? Status::OFFLINE : Status::STARTING
+      @status_provider = StatusProvider.new(initial_status, logger: @options.logger)
+      @listeners = {}
+      @listener_id = 0
+      @listener_mutex = Mutex.new
+      @lifecycle_mutex = Mutex.new
+      @closed = false
+      @close_result = nil
+
+      load_bootstrap(@options.bootstrap) if @options.bootstrap
+      @event_processor = build_event_processor
+      @evaluator = Evaluator.new(
+        flag_getter: ->(key) { @data_store.flag(key) },
+        segment_getter: ->(id) { @data_store.segment(id) },
+        logger: @options.logger
+      )
+      start_synchronizer unless @options.offline
+      @status_provider.update(Status::READY) if @options.offline && @data_store.initialized?
+      @status_provider.wait_until_ready(@options.start_wait) if !@options.offline && @options.start_wait.positive?
+    rescue StandardError => e
+      safe_log(:error, "FeatBit client initialization failed: #{e.message}")
+      @status_provider ||= StatusProvider.new(Status::FAILED)
+      @status_provider.update(Status::FAILED, message: e.message)
+      @event_processor ||= NullEventProcessor.new
+    end
+
+    def initialized?
+      @data_store.initialized?
+    rescue StandardError
+      false
+    end
+
+    def variation(flag_key, user, default_value)
+      variation_detail(flag_key, user, default_value).value
+    rescue StandardError => e
+      safe_log(:error, "FeatBit variation failed: #{e.message}")
+      default_value
+    end
+
+    def variation_detail(flag_key, user, default_value)
+      return safe_detail(flag_key, default_value, :client_not_ready) if @closed || !evaluable?
+
+      normalized_user = normalize_user(user)
+      detail = @evaluator.evaluate(flag_key, normalized_user, default_value)
+      enqueue_evaluation(detail, normalized_user) if detail.success?
+      detail
+    rescue StandardError => e
+      safe_log(:error, "FeatBit variation detail failed: #{e.message}")
+      safe_detail(flag_key, default_value, :error, e.message)
+    end
+
+    def bool_variation(flag_key, user, default_value = false)
+      typed_variation(flag_key, user, default_value, [TrueClass, FalseClass])
+    end
+
+    def string_variation(flag_key, user, default_value = "")
+      typed_variation(flag_key, user, default_value, [String])
+    end
+
+    def number_variation(flag_key, user, default_value = 0)
+      typed_variation(flag_key, user, default_value, [Numeric])
+    end
+
+    def json_variation(flag_key, user, default_value = {})
+      typed_variation(flag_key, user, default_value, [Hash, Array])
+    end
+
+    def track(user, event_name, numeric_value = 1.0)
+      normalized_user = normalize_user(user)
+      return false unless normalized_user.valid? && !event_name.to_s.empty?
+
+      @event_processor.enqueue(
+        user: normalized_user.to_h,
+        metrics: [{
+          eventName: event_name.to_s,
+          numericValue: numeric_value.to_f,
+          route: "index/metric",
+          type: "CustomEvent",
+          appType: "ruby-server-side",
+          timestamp: timestamp_ms
+        }]
+      )
+    rescue StandardError => e
+      safe_log(:warn, "FeatBit track failed: #{e.message}")
+      false
+    end
+
+    def flush
+      @event_processor.flush
+    rescue StandardError
+      false
+    end
+
+    def add_flag_change_listener(callable = nil, &block)
+      listener = callable || block
+      return nil unless listener.respond_to?(:call)
+
+      @listener_mutex.synchronize do
+        @listener_id += 1
+        @listeners[@listener_id] = listener
+        @listener_id
+      end
+    rescue StandardError
+      nil
+    end
+
+    def remove_flag_change_listener(id)
+      @listener_mutex.synchronize { !@listeners.delete(id).nil? }
+    rescue StandardError
+      false
+    end
+
+    def close
+      @lifecycle_mutex.synchronize do
+        return @close_result unless @close_result.nil?
+        return true if @closed
+
+        @closed = true
+      end
+
+      results = [safe_close(@synchronizer), safe_close(@event_processor)]
+      results << safe_status_update(Status::CLOSED)
+      @lifecycle_mutex.synchronize { @close_result = results.all? }
+    rescue StandardError => e
+      safe_log(:warn, "FeatBit client close failed: #{e.message}")
+      false
+    end
+
+    alias stop close
+
+    private
+
+    def evaluable?
+      @data_store.initialized? && [Status::READY, Status::OFFLINE, Status::INTERRUPTED].include?(@status_provider.status)
+    end
+
+    def load_bootstrap(bootstrap)
+      success = @data_store.init(bootstrap)
+      @status_provider.update(success ? Status::READY : Status::FAILED, message: success ? nil : "invalid bootstrap")
+    rescue StandardError => e
+      @status_provider.update(Status::FAILED, message: e.message)
+    end
+
+    def build_event_processor
+      return NullEventProcessor.new if @options.offline || @options.disable_events || !@options.valid?
+      return @options.event_processor_factory.call(@options) if @options.event_processor_factory
+
+      EventProcessor.new(@options)
+    rescue StandardError => e
+      safe_log(:warn, "FeatBit event processor unavailable: #{e.message}")
+      NullEventProcessor.new
+    end
+
+    def start_synchronizer
+      unless @options.valid?
+        @status_provider.update(Status::FAILED, message: "invalid options")
+        return
+      end
+
+      @synchronizer = if @options.synchronizer_factory
+                        @options.synchronizer_factory.call(@options, @data_store, @status_provider, method(:broadcast_flag_change))
+                      else
+                        WebSocketDataSynchronizer.new(
+                          options: @options,
+                          data_store: @data_store,
+                          status_provider: @status_provider,
+                          on_flags_changed: method(:broadcast_flag_change)
+                        )
+                      end
+      @synchronizer.start
+    rescue StandardError => e
+      @status_provider.update(Status::FAILED, message: e.message)
+    end
+
+    def typed_variation(flag_key, user, default_value, expected_types)
+      value = variation(flag_key, user, default_value)
+      expected_types.any? { |type| value.is_a?(type) } ? value : default_value
+    rescue StandardError
+      default_value
+    end
+
+    def normalize_user(user)
+      return user if user.is_a?(User)
+      return User.new(user) if user.is_a?(String)
+
+      if user.is_a?(Hash)
+        key = user["key"] || user[:key] || user["keyId"] || user[:keyId] || user["targeting_key"] || user[:targeting_key]
+        name = user["name"] || user[:name]
+        custom = user.reject { |candidate, _| %w[key keyId targeting_key name].include?(candidate.to_s) }
+        return User.new(key, name: name, custom: custom)
+      end
+
+      User.new("")
+    rescue StandardError
+      User.new("")
+    end
+
+    def enqueue_evaluation(detail, user)
+      @event_processor.enqueue(
+        user: user.to_h,
+        variations: [{
+          featureFlagKey: detail.flag_key,
+          sendToExperiment: detail.send_to_experiment == true,
+          timestamp: timestamp_ms,
+          variation: { id: detail.variation_id, value: serialize_variation_value(detail.value), reason: detail.reason }
+        }]
+      )
+    end
+
+    def serialize_variation_value(value)
+      case value
+      when String then value
+      when TrueClass then "true"
+      when FalseClass then "false"
+      when Hash, Array then JSON.generate(value)
+      when nil then ""
+      else value.to_s
+      end
+    rescue StandardError
+      ""
+    end
+
+    def broadcast_flag_change(flag_key)
+      listeners = @listener_mutex.synchronize { @listeners.values.dup }
+      listeners.each do |listener|
+        listener.call(flag_key)
+      rescue StandardError => e
+        safe_log(:warn, "FeatBit flag listener failed: #{e.message}")
+      end
+      true
+    rescue StandardError
+      false
+    end
+
+    def safe_detail(flag_key, default_value, reason, message = nil)
+      EvaluationDetail.new(
+        value: default_value,
+        reason: Evaluator::REASONS.fetch(reason),
+        flag_key: flag_key,
+        error_kind: reason,
+        error_message: message
+      )
+    end
+
+    def safe_log(level, message)
+      @options&.logger&.public_send(level, message)
+    rescue StandardError
+      nil
+    end
+
+    def safe_close(component)
+      return true unless component
+
+      component.close != false
+    rescue StandardError => e
+      safe_log(:warn, "FeatBit component close failed: #{e.message}")
+      false
+    end
+
+    def safe_status_update(status)
+      @status_provider.update(status) != false
+    rescue StandardError => e
+      safe_log(:warn, "FeatBit status update failed: #{e.message}")
+      false
+    end
+
+    def timestamp_ms
+      (Time.now.to_f * 1000).round
+    end
+  end
+end

data/lib/featbit/data_store.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module FeatBit
+  class InMemoryDataStore
+    def initialize
+      @flags = {}.freeze
+      @segments = {}.freeze
+      @flag_versions = {}.freeze
+      @segment_versions = {}.freeze
+      @version = 0
+      @initialized = false
+      @mutex = Mutex.new
+    end
+
+    def initialized?
+      @mutex.synchronize { @initialized }
+    rescue StandardError
+      false
+    end
+
+    def version
+      @mutex.synchronize { @version }
+    rescue StandardError
+      0
+    end
+
+    def flag(key)
+      item = @mutex.synchronize { @flags[key.to_s] }
+      item && !fetch(item, "isArchived", false) ? deep_dup(item) : nil
+    rescue StandardError
+      nil
+    end
+
+    def segment(id)
+      item = @mutex.synchronize { @segments[id.to_s] }
+      item && !fetch(item, "isArchived", false) ? deep_dup(item) : nil
+    rescue StandardError
+      nil
+    end
+
+    def all_flags
+      snapshot = @mutex.synchronize { @flags }
+      snapshot.each_with_object({}) do |(key, value), result|
+        result[key] = deep_dup(value) unless fetch(value, "isArchived", false)
+      end
+    rescue StandardError
+      {}
+    end
+
+    def init(payload, version: nil)
+      data = normalize_payload(payload)
+      flags = Array(fetch(data, "featureFlags", [])).to_h do |flag|
+        [fetch(flag, "key").to_s, normalize_flag(flag)]
+      end
+      segments = Array(fetch(data, "segments", [])).to_h do |segment|
+        [fetch(segment, "id").to_s, normalize_hash(segment)]
+      end
+      incoming_version = version || derive_version(flags.values + segments.values)
+      incoming_version = 1 if incoming_version.to_i <= 0
+      flag_versions = entity_versions(flags, version)
+      segment_versions = entity_versions(segments, version)
+
+      @mutex.synchronize do
+        return false if @initialized && incoming_version.to_i <= @version
+
+        @flags = deep_freeze(flags)
+        @segments = deep_freeze(segments)
+        @flag_versions = deep_freeze(flag_versions)
+        @segment_versions = deep_freeze(segment_versions)
+        @version = incoming_version.to_i
+        @initialized = true
+      end
+      true
+    rescue StandardError
+      false
+    end
+
+    def upsert(kind, item, version: nil)
+      normalized = normalize_hash(item)
+      key = kind.to_sym == :flags ? fetch(normalized, "key") : fetch(normalized, "id")
+      return false if key.to_s.empty?
+
+      incoming_version = version || item_version(normalized)
+      incoming_version = @mutex.synchronize { @version + 1 } if incoming_version.to_i <= 0
+      @mutex.synchronize do
+        if kind.to_sym == :flags
+          return false if incoming_version.to_i <= @flag_versions.fetch(key.to_s, 0)
+
+          copy = @flags.dup
+          version_copy = @flag_versions.dup
+          copy[key.to_s] = normalize_flag(normalized)
+          version_copy[key.to_s] = incoming_version.to_i
+          @flags = deep_freeze(copy)
+          @flag_versions = deep_freeze(version_copy)
+        else
+          return false if incoming_version.to_i <= @segment_versions.fetch(key.to_s, 0)
+
+          copy = @segments.dup
+          version_copy = @segment_versions.dup
+          copy[key.to_s] = normalized
+          version_copy[key.to_s] = incoming_version.to_i
+          @segments = deep_freeze(copy)
+          @segment_versions = deep_freeze(version_copy)
+        end
+        @version = [@version, incoming_version.to_i].max
+        @initialized = true
+      end
+      true
+    rescue StandardError
+      false
+    end
+
+    private
+
+    def normalize_payload(payload)
+      parsed = payload.is_a?(String) ? JSON.parse(payload) : payload
+      parsed = fetch(parsed, "data", parsed)
+      normalize_hash(parsed || {})
+    end
+
+    def normalize_flag(flag)
+      normalized = normalize_hash(flag)
+      variations = Array(fetch(normalized, "variations", []))
+      normalized["variationMap"] = variations.to_h do |variation|
+        [fetch(variation, "id").to_s, fetch(variation, "value")]
+      end
+      normalized
+    end
+
+    def normalize_hash(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, item), result| result[key.to_s] = normalize_hash(item) }
+      when Array
+        value.map { |item| normalize_hash(item) }
+      else
+        value
+      end
+    end
+
+    def derive_version(items)
+      items.map { |item| item_version(item) }.max.to_i
+    end
+
+    def entity_versions(items, snapshot_version)
+      items.transform_values do |item|
+        next snapshot_version.to_i if snapshot_version
+
+        version = item_version(item)
+        version.positive? ? version : 1
+      end
+    end
+
+    def item_version(item)
+      explicit = fetch(item, "timestamp")
+      return explicit.to_i if explicit
+
+      updated = fetch(item, "updatedAt")
+      updated ? (Time.parse(updated.to_s).to_f * 1000).to_i : 0
+    rescue StandardError
+      0
+    end
+
+    def fetch(hash, key, default = nil)
+      hash.is_a?(Hash) ? hash.fetch(key.to_s, hash.fetch(key.to_sym, default)) : default
+    end
+
+    def deep_dup(value)
+      Marshal.load(Marshal.dump(value))
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash
+        value.each do |key, item|
+          deep_freeze(key)
+          deep_freeze(item)
+        end
+      when Array
+        value.each { |item| deep_freeze(item) }
+      end
+      value.freeze
+    end
+  end
+end

data/lib/featbit/evaluation_detail.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module FeatBit
+  EvaluationDetail = Struct.new(
+    :value, :reason, :variation_id, :flag_key, :flag_name, :send_to_experiment, :error_kind, :error_message,
+    keyword_init: true
+  ) do
+    def success?
+      error_kind.nil?
+    end
+  end
+end