featureflip 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 193c7bdc8f5d87d2bd2705848bbe245c3defb24f7e00328166f5add6fa251f4c
+  data.tar.gz: 9f33416673fde7b3621dc8cbcf06dc605a773c15ce49a2ed6df4fff6f2bec7a7
+SHA512:
+  metadata.gz: 54f640cbb297fd817c0475fce44baae2603da0216c456c7fc76323c7ee88e86588f9763d42a18c8ec8e17eab734095e229165d5d9cd997693f420bf95f4ad30e
+  data.tar.gz: f472d47b4c48cbb546b64db5a3dff43cdd1251a97dfb37f559522bc0ff0f820a4f52d7188eed949e4f38f48010492e2b9ccc2a376f1fe8ad693adc7bf4855185

data/lib/featureflip/client.rb

@@ -0,0 +1,247 @@
+require "timeout"
+
+module Featureflip
+  class Client
+    attr_reader :initialized
+    alias_method :initialized?, :initialized
+
+    def initialize(sdk_key: nil, config: nil)
+      @sdk_key = sdk_key || ENV["FEATUREFLIP_SDK_KEY"]
+      raise ConfigurationError, "SDK key is required. Pass sdk_key parameter or set FEATUREFLIP_SDK_KEY env var." unless @sdk_key
+
+      @config = config || Config.new
+      @store = Store::FlagStore.new
+      @evaluator = Evaluation::Evaluator.new
+      @initialized = false
+      @closed = false
+      @test_mode = false
+      @test_values = {}
+      @http_client = nil
+      @streaming_handler = nil
+      @polling_handler = nil
+      @event_processor = nil
+
+      initialize!
+    end
+
+    def bool_variation(key, context, default_value)
+      evaluate_flag(key, context, default_value)
+    end
+
+    def string_variation(key, context, default_value)
+      evaluate_flag(key, context, default_value)
+    end
+
+    def number_variation(key, context, default_value)
+      evaluate_flag(key, context, default_value)
+    end
+
+    def json_variation(key, context, default_value)
+      evaluate_flag(key, context, default_value)
+    end
+
+    def variation_detail(key, context, default_value)
+      context = normalize_context(context)
+
+      if @test_mode
+        value = @test_values.fetch(key, default_value)
+        reason = @test_values.key?(key) ? "Fallthrough" : "FlagNotFound"
+        return Models::EvaluationDetail.new(value: value, reason: reason)
+      end
+
+      flag = @store.get_flag(key)
+      unless flag
+        record_evaluation(key, context, nil)
+        return Models::EvaluationDetail.new(value: default_value, reason: "FlagNotFound")
+      end
+
+      result = @evaluator.evaluate(flag, context, get_segment: method(:get_segment))
+      value = result.value.nil? ? default_value : result.value
+      record_evaluation(key, context, result.variation_key)
+
+      Models::EvaluationDetail.new(
+        value: value,
+        reason: result.reason,
+        rule_id: result.rule_id,
+        variation_key: result.variation_key
+      )
+    rescue StandardError
+      Models::EvaluationDetail.new(value: default_value, reason: "Error")
+    end
+
+    def track(event_key, context, metadata = nil)
+      return unless @event_processor
+
+      context = normalize_context(context)
+      @event_processor.queue_event({
+        type: "Custom",
+        flagKey: event_key,
+        userId: context["user_id"]&.to_s,
+        metadata: metadata || {},
+        timestamp: Time.now.utc.iso8601
+      })
+    end
+
+    def identify(context)
+      return unless @event_processor
+
+      context = normalize_context(context)
+      @event_processor.queue_event({
+        type: "Identify",
+        flagKey: "$identify",
+        userId: context["user_id"]&.to_s,
+        timestamp: Time.now.utc.iso8601
+      })
+    end
+
+    def flush
+      @event_processor&.flush
+    end
+
+    def close
+      @closed = true
+      @streaming_handler&.stop
+      @streaming_handler = nil
+      @polling_handler&.stop
+      @polling_handler = nil
+      @event_processor&.stop
+      @event_processor = nil
+    end
+
+    def restart
+      return if @closed
+
+      @streaming_handler&.stop
+      @polling_handler&.stop
+      @event_processor&.stop
+
+      if @config.streaming
+        start_streaming
+      else
+        start_polling
+      end
+      start_event_processor if @config.send_events
+    end
+
+    def self.for_testing(flags)
+      instance = allocate
+      instance.instance_variable_set(:@sdk_key, "test-key")
+      instance.instance_variable_set(:@config, Config.new)
+      instance.instance_variable_set(:@store, Store::FlagStore.new)
+      instance.instance_variable_set(:@evaluator, Evaluation::Evaluator.new)
+      instance.instance_variable_set(:@initialized, true)
+      instance.instance_variable_set(:@closed, false)
+      instance.instance_variable_set(:@test_mode, true)
+      instance.instance_variable_set(:@test_values, flags.dup)
+      instance.instance_variable_set(:@http_client, nil)
+      instance.instance_variable_set(:@streaming_handler, nil)
+      instance.instance_variable_set(:@polling_handler, nil)
+      instance.instance_variable_set(:@event_processor, nil)
+      instance
+    end
+
+    private
+
+    def initialize!
+      @http_client = Http::Client.new(@sdk_key, @config)
+      fetch_initial_flags
+      start_data_source
+      start_event_processor if @config.send_events
+    end
+
+    def fetch_initial_flags
+      Timeout.timeout(@config.init_timeout) do
+        flags, segments = @http_client.get_flags
+        @store.init(flags, segments)
+        @initialized = true
+      end
+    rescue Timeout::Error
+      raise InitializationError, "Initialization timed out after #{@config.init_timeout}s"
+    rescue InitializationError
+      raise
+    rescue StandardError => e
+      raise InitializationError, "Failed to initialize: #{e.message}"
+    end
+
+    def start_data_source
+      return if @closed
+
+      if @config.streaming
+        start_streaming
+      else
+        start_polling
+      end
+    end
+
+    def start_streaming
+      @streaming_handler = DataSource::StreamingHandler.new(
+        sdk_key: @sdk_key,
+        config: @config,
+        http_client: @http_client,
+        on_flag_updated: ->(flag) { @store.upsert(flag) },
+        on_flag_deleted: ->(key) { @store.remove_flag(key) },
+        on_segment_updated: ->(flags, segments) { @store.init(flags, segments) },
+        on_error: ->(_err) { },
+        on_give_up: -> { fallback_to_polling }
+      )
+      @streaming_handler.start
+    end
+
+    def fallback_to_polling
+      @config.logger&.warn("Featureflip: streaming retries exhausted, falling back to polling")
+      @streaming_handler = nil
+      start_polling
+    end
+
+    def start_polling
+      @polling_handler = DataSource::PollingHandler.new(
+        http_client: @http_client,
+        config: @config,
+        on_update: ->(flags, segments) { @store.init(flags, segments) },
+        on_error: ->(_err) { }
+      )
+      @polling_handler.start
+    end
+
+    def start_event_processor
+      @event_processor = Events::EventProcessor.new(
+        @http_client,
+        flush_interval: @config.flush_interval,
+        flush_batch_size: @config.flush_batch_size
+      )
+      @event_processor.start
+    end
+
+    def evaluate_flag(key, context, default_value)
+      if @test_mode
+        return @test_values.fetch(key, default_value)
+      end
+
+      detail = variation_detail(key, context, default_value)
+      detail.value
+    rescue StandardError
+      default_value
+    end
+
+    def get_segment(key)
+      @store.get_segment(key)
+    end
+
+    def normalize_context(context)
+      return {} if context.nil?
+      context.transform_keys(&:to_s)
+    end
+
+    def record_evaluation(key, context, variation_key)
+      return unless @event_processor
+
+      @event_processor.queue_event({
+        type: "Evaluation",
+        flagKey: key,
+        userId: context["user_id"]&.to_s,
+        variation: variation_key,
+        timestamp: Time.now.utc.iso8601
+      })
+    end
+  end
+end

data/lib/featureflip/config.rb

@@ -0,0 +1,66 @@
+module Featureflip
+  class Config
+    attr_accessor :sdk_key, :base_url, :streaming, :poll_interval, :flush_interval,
+                  :flush_batch_size, :init_timeout, :connect_timeout, :read_timeout,
+                  :max_stream_retries, :send_events, :logger
+
+    def initialize(
+      sdk_key: nil,
+      base_url: "https://eval.featureflip.io",
+      streaming: true,
+      poll_interval: 30,
+      flush_interval: 30,
+      flush_batch_size: 100,
+      init_timeout: 10,
+      connect_timeout: 5,
+      read_timeout: 10,
+      max_stream_retries: 5,
+      send_events: true,
+      logger: nil
+    )
+      @sdk_key = sdk_key
+      @base_url = base_url
+      @streaming = streaming
+      @poll_interval = poll_interval
+      @flush_interval = flush_interval
+      @flush_batch_size = flush_batch_size
+      @init_timeout = init_timeout
+      @connect_timeout = connect_timeout
+      @read_timeout = read_timeout
+      @max_stream_retries = max_stream_retries
+      @send_events = send_events
+      @logger = logger || default_logger
+
+      validate!
+    end
+
+    def validate!
+      finalize!
+      validate_positive_fields!
+    end
+
+    private
+
+    def finalize!
+      @base_url = @base_url.to_s.gsub(%r{/+$}, "")
+    end
+
+    def validate_positive_fields!
+      %i[poll_interval flush_interval flush_batch_size init_timeout connect_timeout read_timeout].each do |field|
+        value = send(field)
+        if value <= 0
+          raise ConfigurationError, "#{field} must be positive, got #{value}"
+        end
+      end
+    end
+
+    def default_logger
+      if defined?(Rails) && Rails.respond_to?(:logger)
+        Rails.logger
+      else
+        require "logger"
+        ::Logger.new($stdout, level: ::Logger::INFO)
+      end
+    end
+  end
+end

data/lib/featureflip/data_source/polling.rb

@@ -0,0 +1,44 @@
+module Featureflip
+  module DataSource
+    class PollingHandler
+      def initialize(http_client:, config:, on_update:, on_error:)
+        @http_client = http_client
+        @config = config
+        @on_update = on_update
+        @on_error = on_error
+        @stop_flag = false
+        @thread = nil
+      end
+
+      def start
+        @stop_flag = false
+        @thread = Thread.new { run }
+      end
+
+      def stop
+        @stop_flag = true
+        @thread&.wakeup rescue nil
+        @thread&.join(5)
+        @thread = nil
+      end
+
+      private
+
+      def run
+        until @stop_flag
+          begin
+            flags, segments = @http_client.get_flags
+            @on_update.call(flags, segments)
+          rescue StandardError => e
+            @on_error.call(e)
+          end
+          elapsed = 0
+          while elapsed < @config.poll_interval && !@stop_flag
+            sleep(1)
+            elapsed += 1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/featureflip/data_source/streaming.rb

@@ -0,0 +1,121 @@
+require "net/http"
+require "uri"
+require "json"
+
+module Featureflip
+  module DataSource
+    class StreamingHandler
+      def initialize(sdk_key:, config:, http_client:, on_flag_updated:, on_flag_deleted:, on_segment_updated:, on_error:, on_give_up: nil)
+        @sdk_key = sdk_key
+        @config = config
+        @http_client = http_client
+        @on_flag_updated = on_flag_updated
+        @on_flag_deleted = on_flag_deleted
+        @on_segment_updated = on_segment_updated
+        @on_error = on_error
+        @on_give_up = on_give_up
+        @stop_flag = false
+        @thread = nil
+        @retry_count = 0
+        @current_event_type = nil
+        @current_data = nil
+      end
+
+      def start
+        @stop_flag = false
+        @retry_count = 0
+        @thread = Thread.new { run }
+      end
+
+      def stop
+        @stop_flag = true
+        @thread&.wakeup rescue nil
+        @thread&.join(5)
+        @thread = nil
+      end
+
+      private
+
+      def run
+        until @stop_flag
+          begin
+            connect
+          rescue StandardError => e
+            break if @stop_flag
+            @on_error.call(e)
+            @retry_count += 1
+            if @retry_count > @config.max_stream_retries
+              @on_give_up&.call
+              break
+            end
+            delay = [2**(@retry_count - 1), 30].min
+            sleep(delay)
+          end
+        end
+      end
+
+      def connect
+        uri = URI("#{@config.base_url}/v1/sdk/stream")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @config.connect_timeout
+        http.read_timeout = 300 # 5 min — detect silent TCP drops
+
+        req = Net::HTTP::Get.new(uri.request_uri)
+        req["Authorization"] = @sdk_key
+        req["Accept"] = "text/event-stream"
+        req["User-Agent"] = "featureflip-ruby/#{Featureflip::VERSION}"
+
+        http.request(req) do |response|
+          unless response.is_a?(Net::HTTPSuccess)
+            raise Featureflip::Error, "SSE connection failed: #{response.code}"
+          end
+
+          @retry_count = 0
+          @current_event_type = nil
+          @current_data = nil
+
+          response.read_body do |chunk|
+            break if @stop_flag
+            chunk.each_line do |line|
+              process_sse_line(line.strip)
+            end
+          end
+        end
+      end
+
+      def process_sse_line(line)
+        if line.start_with?("event: ")
+          @current_event_type = line[7..]
+        elsif line.start_with?("data: ")
+          @current_data = line[6..]
+        elsif line.empty? && @current_event_type && @current_data
+          handle_event(@current_event_type, @current_data)
+          @current_event_type = nil
+          @current_data = nil
+        end
+      end
+
+      def handle_event(event_type, data)
+        case event_type
+        when "flag.created", "flag.updated"
+          payload = JSON.parse(data)
+          key = payload["key"]
+          return if key.nil? || key.empty?
+          flag = @http_client.get_flag(key)
+          @on_flag_updated.call(flag)
+        when "flag.deleted"
+          payload = JSON.parse(data)
+          key = payload["key"]
+          return if key.nil? || key.empty?
+          @on_flag_deleted.call(key)
+        when "segment.updated"
+          flags, segments = @http_client.get_flags
+          @on_segment_updated.call(flags, segments)
+        end
+      rescue StandardError
+        # Swallow event processing errors
+      end
+    end
+  end
+end

data/lib/featureflip/errors.rb

@@ -0,0 +1,5 @@
+module Featureflip
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class InitializationError < Error; end
+end

data/lib/featureflip/evaluation/bucketing.rb

@@ -0,0 +1,14 @@
+require "digest/md5"
+
+module Featureflip
+  module Evaluation
+    module Bucketing
+      def self.compute_bucket(salt, value)
+        input = "#{salt}:#{value}"
+        hash_bytes = Digest::MD5.digest(input)
+        hash_int = hash_bytes[0, 4].unpack1("V")
+        hash_int % 100
+      end
+    end
+  end
+end

data/lib/featureflip/evaluation/condition_evaluator.rb

@@ -0,0 +1,88 @@
+module Featureflip
+  module Evaluation
+    class ConditionEvaluator
+      def evaluate_condition(condition, context)
+        attr_value = context[condition.attribute]
+
+        return condition.negate if attr_value.nil?
+
+        str_value = attr_value.to_s.downcase
+        targets = condition.values.map { |v| v.to_s.downcase }
+
+        result = evaluate_operator(condition.operator, str_value, targets)
+        condition.negate ? !result : result
+      end
+
+      def evaluate_conditions(conditions, logic, context)
+        return true if conditions.empty?
+
+        if logic == "And"
+          conditions.all? { |c| evaluate_condition(c, context) }
+        else
+          conditions.any? { |c| evaluate_condition(c, context) }
+        end
+      end
+
+      def evaluate_condition_groups(condition_groups, context)
+        return true if condition_groups.nil? || condition_groups.empty?
+
+        condition_groups.all? do |group|
+          evaluate_conditions(group.conditions, group.operator, context)
+        end
+      end
+
+      private
+
+      def evaluate_operator(operator, value, targets)
+        case operator
+        when "Equals"
+          targets.any? { |t| value == t }
+        when "NotEquals"
+          targets.all? { |t| value != t }
+        when "Contains"
+          targets.any? { |t| value.include?(t) }
+        when "NotContains"
+          targets.all? { |t| !value.include?(t) }
+        when "StartsWith"
+          targets.any? { |t| value.start_with?(t) }
+        when "EndsWith"
+          targets.any? { |t| value.end_with?(t) }
+        when "In"
+          targets.include?(value)
+        when "NotIn"
+          !targets.include?(value)
+        when "MatchesRegex"
+          targets.any? do |t|
+            Regexp.new(t, Regexp::IGNORECASE).match?(value)
+          rescue RegexpError
+            false
+          end
+        when "GreaterThan"
+          compare_numeric(value, targets[0], :>)
+        when "GreaterThanOrEqual"
+          compare_numeric(value, targets[0], :>=)
+        when "LessThan"
+          compare_numeric(value, targets[0], :<)
+        when "LessThanOrEqual"
+          compare_numeric(value, targets[0], :<=)
+        when "Before"
+          return false if targets.empty?
+          value < targets[0]
+        when "After"
+          return false if targets.empty?
+          value > targets[0]
+        else
+          false
+        end
+      end
+
+      def compare_numeric(value, target, op)
+        val = Float(value)
+        tgt = Float(target)
+        val.send(op, tgt)
+      rescue ArgumentError, TypeError
+        false
+      end
+    end
+  end
+end

data/lib/featureflip/evaluation/evaluator.rb

@@ -0,0 +1,89 @@
+require_relative "condition_evaluator"
+require_relative "bucketing"
+
+module Featureflip
+  module Evaluation
+    class Evaluator
+      def initialize
+        @condition_evaluator = ConditionEvaluator.new
+      end
+
+      def evaluate(flag, context, get_segment: nil)
+        unless flag.enabled
+          variation = flag.get_variation(flag.off_variation)
+          return Models::EvaluationDetail.new(
+            value: variation&.value,
+            reason: "FlagDisabled",
+            variation_key: flag.off_variation
+          )
+        end
+
+        sorted_rules = flag.rules.sort_by(&:priority)
+        sorted_rules.each do |rule|
+          conditions_match = if rule.segment_key && get_segment
+            segment = get_segment.call(rule.segment_key)
+            if segment
+              @condition_evaluator.evaluate_conditions(
+                segment.conditions, segment.condition_logic, context
+              )
+            else
+              false
+            end
+          else
+            @condition_evaluator.evaluate_condition_groups(
+              rule.condition_groups, context
+            )
+          end
+
+          if conditions_match
+            variation_key = resolve_serve(rule.serve, context)
+            variation = flag.get_variation(variation_key)
+            return Models::EvaluationDetail.new(
+              value: variation&.value,
+              reason: "RuleMatch",
+              rule_id: rule.id,
+              variation_key: variation_key
+            )
+          end
+        end
+
+        variation_key = resolve_serve(flag.fallthrough, context)
+        variation = flag.get_variation(variation_key)
+        Models::EvaluationDetail.new(
+          value: variation&.value,
+          reason: "Fallthrough",
+          variation_key: variation_key
+        )
+      end
+
+      private
+
+      def resolve_serve(serve, context)
+        if serve.type == "Fixed"
+          serve.variation || ""
+        else
+          resolve_rollout(serve, context)
+        end
+      end
+
+      def resolve_rollout(serve, context)
+        bucket_by = serve.bucket_by || "userId"
+        bucket_value = context[bucket_by]
+        # Alias "userId" <-> "user_id" for the built-in user identifier
+        bucket_value = context["user_id"] if bucket_value.nil? && bucket_by == "userId"
+        bucket_value = context["userId"] if bucket_value.nil? && bucket_by == "user_id"
+        bucket_value_str = bucket_value.nil? ? "" : bucket_value.to_s
+
+        bucket = Bucketing.compute_bucket(serve.salt || "", bucket_value_str)
+
+        cumulative = 0
+        (serve.variations || []).each do |wv|
+          cumulative += wv.weight
+          return wv.key if bucket < cumulative
+        end
+
+        serve.variations&.last&.key || ""
+      end
+    end
+  end
+end

data/lib/featureflip/events/event.rb

@@ -0,0 +1,5 @@
+module Featureflip
+  module Events
+    # Event types are plain hashes with :type key
+  end
+end

data/lib/featureflip/events/event_processor.rb

@@ -0,0 +1,63 @@
+module Featureflip
+  module Events
+    class EventProcessor
+      def initialize(http_client, flush_interval: 30, flush_batch_size: 100)
+        @http_client = http_client
+        @flush_interval = flush_interval
+        @flush_batch_size = flush_batch_size
+        @queue = []
+        @mutex = Mutex.new
+        @stop_flag = false
+        @thread = nil
+      end
+
+      def queue_event(event)
+        should_flush = false
+        @mutex.synchronize do
+          @queue << event
+          should_flush = @queue.length >= @flush_batch_size
+        end
+        flush if should_flush
+      end
+
+      def flush
+        events_to_send = nil
+        @mutex.synchronize do
+          return if @queue.empty?
+          events_to_send = @queue.dup
+          @queue.clear
+        end
+
+        return unless events_to_send&.any?
+
+        @http_client.post_events(events_to_send)
+      rescue StandardError
+        # Events are best-effort — drop on failure
+      end
+
+      def start
+        @stop_flag = false
+        @thread = Thread.new do
+          elapsed = 0
+          until @stop_flag
+            sleep(1)
+            elapsed += 1
+            queue_size = @mutex.synchronize { @queue.length }
+            if elapsed >= @flush_interval || queue_size >= @flush_batch_size
+              elapsed = 0
+              flush unless @stop_flag
+            end
+          end
+        end
+      end
+
+      def stop
+        @stop_flag = true
+        @thread&.wakeup rescue nil
+        @thread&.join(5)
+        @thread = nil
+        flush
+      end
+    end
+  end
+end

data/lib/featureflip/http/client.rb

@@ -0,0 +1,141 @@
+require "json"
+require "net/http"
+require "uri"
+
+module Featureflip
+  module Http
+    class Client
+      def initialize(sdk_key, config)
+        @sdk_key = sdk_key
+        @config = config
+        @base_url = config.base_url
+      end
+
+      def get_flags
+        response = request(:get, "/v1/sdk/flags")
+        data = JSON.parse(response.body)
+        flags = (data["flags"] || []).map { |f| parse_flag(f) }
+        segments = (data["segments"] || []).map { |s| parse_segment(s) }
+        [flags, segments]
+      end
+
+      def get_flag(key)
+        response = request(:get, "/v1/sdk/flags/#{key}")
+        parse_flag(JSON.parse(response.body))
+      end
+
+      def post_events(events)
+        request(:post, "/v1/sdk/events", { events: events })
+      end
+
+      def close
+        # No persistent connection to close with net/http
+      end
+
+      private
+
+      def request(method, path, body = nil, retries: 1)
+        uri = URI("#{@base_url}#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @config.connect_timeout
+        http.read_timeout = @config.read_timeout
+
+        req = case method
+        when :get
+          Net::HTTP::Get.new(uri.request_uri)
+        when :post
+          r = Net::HTTP::Post.new(uri.request_uri)
+          r.body = JSON.generate(body)
+          r
+        end
+
+        req["Authorization"] = @sdk_key
+        req["Content-Type"] = "application/json"
+        req["User-Agent"] = "featureflip-ruby/#{Featureflip::VERSION}"
+
+        response = http.request(req)
+
+        if response.is_a?(Net::HTTPServerError) && retries > 0
+          sleep(1)
+          return request(method, path, body, retries: retries - 1)
+        end
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise Featureflip::Error, "HTTP #{response.code}: #{path}"
+        end
+
+        response
+      rescue IOError, Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ETIMEDOUT,
+             Net::OpenTimeout, Net::ReadTimeout => e
+        raise if retries <= 0
+        sleep(1)
+        request(method, path, body, retries: retries - 1)
+      end
+
+      def parse_flag(data)
+        Models::FlagConfiguration.new(
+          key: data["key"],
+          version: data["version"],
+          type: data["type"],
+          enabled: data["enabled"],
+          variations: (data["variations"] || []).map { |v| Models::Variation.new(key: v["key"], value: v["value"]) },
+          rules: (data["rules"] || []).map { |r| parse_rule(r) },
+          fallthrough: parse_serve(data["fallthrough"]),
+          off_variation: data["offVariation"]
+        )
+      end
+
+      def parse_rule(data)
+        condition_groups = (data["conditionGroups"] || []).map { |g| parse_condition_group(g) }
+
+        Models::TargetingRule.new(
+          id: data["id"],
+          priority: data["priority"],
+          condition_groups: condition_groups,
+          serve: parse_serve(data["serve"]),
+          segment_key: data["segmentKey"]
+        )
+      end
+
+      def parse_condition_group(data)
+        Models::ConditionGroup.new(
+          operator: data["operator"] || "And",
+          conditions: (data["conditions"] || []).map { |c| parse_condition(c) }
+        )
+      end
+
+      def parse_condition(data)
+        Models::Condition.new(
+          attribute: data["attribute"],
+          operator: data["operator"],
+          values: data["values"],
+          negate: data["negate"] || false
+        )
+      end
+
+      def parse_serve(data)
+        variations = if data["variations"]
+          data["variations"].map { |v| Models::WeightedVariation.new(key: v["key"], weight: v["weight"]) }
+        end
+
+        Models::ServeConfig.new(
+          type: data["type"],
+          variation: data["variation"],
+          bucket_by: data["bucketBy"],
+          salt: data["salt"],
+          variations: variations
+        )
+      end
+
+      def parse_segment(data)
+        Models::Segment.new(
+          key: data["key"],
+          version: data["version"],
+          conditions: (data["conditions"] || []).map { |c| parse_condition(c) },
+          condition_logic: data["conditionLogic"] || "And"
+        )
+      end
+    end
+  end
+end

data/lib/featureflip/models/evaluation_detail.rb

@@ -0,0 +1,9 @@
+module Featureflip
+  module Models
+    EvaluationDetail = Struct.new(:value, :reason, :rule_id, :variation_key, keyword_init: true) do
+      def initialize(value:, reason:, rule_id: nil, variation_key: nil)
+        super
+      end
+    end
+  end
+end

data/lib/featureflip/models/flag.rb

@@ -0,0 +1,38 @@
+module Featureflip
+  module Models
+    Variation = Struct.new(:key, :value, keyword_init: true)
+
+    WeightedVariation = Struct.new(:key, :weight, keyword_init: true)
+
+    Condition = Struct.new(:attribute, :operator, :values, :negate, keyword_init: true) do
+      def initialize(attribute:, operator:, values:, negate: false)
+        super
+      end
+    end
+
+    ServeConfig = Struct.new(:type, :variation, :bucket_by, :salt, :variations, keyword_init: true) do
+      def initialize(type:, variation: nil, bucket_by: nil, salt: nil, variations: nil)
+        super
+      end
+    end
+
+    ConditionGroup = Struct.new(:operator, :conditions, keyword_init: true) do
+      def initialize(operator: "And", conditions: [])
+        super
+      end
+    end
+
+    TargetingRule = Struct.new(:id, :priority, :condition_groups, :serve, :segment_key, keyword_init: true) do
+      def initialize(id:, priority:, condition_groups:, serve:, segment_key: nil)
+        super
+      end
+    end
+
+    FlagConfiguration = Struct.new(:key, :version, :type, :enabled, :variations, :rules, :fallthrough, :off_variation, keyword_init: true) do
+      def get_variation(key)
+        @variations_by_key ||= variations.each_with_object({}) { |v, h| h[v.key] = v }
+        @variations_by_key[key]
+      end
+    end
+  end
+end

data/lib/featureflip/models/segment.rb

@@ -0,0 +1,5 @@
+module Featureflip
+  module Models
+    Segment = Struct.new(:key, :version, :conditions, :condition_logic, keyword_init: true)
+  end
+end

data/lib/featureflip/store/flag_store.rb

@@ -0,0 +1,44 @@
+module Featureflip
+  module Store
+    class FlagStore
+      def initialize
+        @flags = {}
+        @segments = {}
+        @mutex = Mutex.new
+      end
+
+      def init(flags, segments)
+        @mutex.synchronize do
+          @flags.clear
+          @segments.clear
+          flags.each { |f| @flags[f.key] = f }
+          segments.each { |s| @segments[s.key] = s }
+        end
+      end
+
+      def get_flag(key)
+        @mutex.synchronize { @flags[key] }
+      end
+
+      def get_segment(key)
+        @mutex.synchronize { @segments[key] }
+      end
+
+      def all_flags
+        @mutex.synchronize { @flags.values }
+      end
+
+      def upsert(flag)
+        @mutex.synchronize do
+          existing = @flags[flag.key]
+          return if existing && existing.version >= flag.version
+          @flags[flag.key] = flag
+        end
+      end
+
+      def remove_flag(key)
+        @mutex.synchronize { @flags.delete(key) }
+      end
+    end
+  end
+end

data/lib/featureflip/version.rb

@@ -0,0 +1,3 @@
+module Featureflip
+  VERSION = "0.1.0"
+end

data/lib/featureflip.rb

@@ -0,0 +1,92 @@
+require_relative "featureflip/version"
+require_relative "featureflip/errors"
+require_relative "featureflip/config"
+require_relative "featureflip/models/flag"
+require_relative "featureflip/models/segment"
+require_relative "featureflip/models/evaluation_detail"
+require_relative "featureflip/evaluation/bucketing"
+require_relative "featureflip/evaluation/condition_evaluator"
+require_relative "featureflip/evaluation/evaluator"
+require_relative "featureflip/store/flag_store"
+require_relative "featureflip/http/client"
+require_relative "featureflip/events/event"
+require_relative "featureflip/events/event_processor"
+require_relative "featureflip/data_source/streaming"
+require_relative "featureflip/data_source/polling"
+require_relative "featureflip/client"
+
+module Featureflip
+  @mutex = Mutex.new
+
+  class << self
+    attr_reader :default_client
+
+    def configure
+      @mutex.synchronize do
+        @config = Config.new
+        yield @config if block_given?
+        @config.validate!
+        @default_client = Client.new(sdk_key: @config.sdk_key, config: @config)
+      end
+    end
+
+    def bool_variation(key, context, default_value)
+      ensure_configured!
+      @default_client.bool_variation(key, context, default_value)
+    end
+
+    def string_variation(key, context, default_value)
+      ensure_configured!
+      @default_client.string_variation(key, context, default_value)
+    end
+
+    def number_variation(key, context, default_value)
+      ensure_configured!
+      @default_client.number_variation(key, context, default_value)
+    end
+
+    def json_variation(key, context, default_value)
+      ensure_configured!
+      @default_client.json_variation(key, context, default_value)
+    end
+
+    def variation_detail(key, context, default_value)
+      ensure_configured!
+      @default_client.variation_detail(key, context, default_value)
+    end
+
+    def track(event_key, context, metadata = nil)
+      ensure_configured!
+      @default_client.track(event_key, context, metadata)
+    end
+
+    def identify(context)
+      ensure_configured!
+      @default_client.identify(context)
+    end
+
+    def flush
+      ensure_configured!
+      @default_client.flush
+    end
+
+    def close
+      @mutex.synchronize do
+        return unless @default_client
+        @default_client.close
+        @default_client = nil
+      end
+    end
+
+    def restart
+      ensure_configured!
+      @default_client.restart
+    end
+
+    private
+
+    def ensure_configured!
+      raise Error, "Featureflip not configured. Call Featureflip.configure first." unless @default_client
+    end
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: featureflip
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Featureflip
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: Server-side SDK for evaluating feature flags with Featureflip
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/featureflip.rb
+- lib/featureflip/client.rb
+- lib/featureflip/config.rb
+- lib/featureflip/data_source/polling.rb
+- lib/featureflip/data_source/streaming.rb
+- lib/featureflip/errors.rb
+- lib/featureflip/evaluation/bucketing.rb
+- lib/featureflip/evaluation/condition_evaluator.rb
+- lib/featureflip/evaluation/evaluator.rb
+- lib/featureflip/events/event.rb
+- lib/featureflip/events/event_processor.rb
+- lib/featureflip/http/client.rb
+- lib/featureflip/models/evaluation_detail.rb
+- lib/featureflip/models/flag.rb
+- lib/featureflip/models/segment.rb
+- lib/featureflip/store/flag_store.rb
+- lib/featureflip/version.rb
+homepage: https://featureflip.io
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://featureflip.io
+  documentation_uri: https://featureflip.io/docs/sdks/ruby/
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Featureflip feature flag SDK for Ruby
+test_files: []