flagkit 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3b5c7ff90342f128e65ed9b5dc73194ed8ba7bdb49dc714504c4c70461c8bedf
+  data.tar.gz: 6f28730d3ae15d635ae1180678f2dcbf734b39890b21ac15e4bd2c2825df32ec
+SHA512:
+  metadata.gz: 43f83a9bfd0433d3c8dfd15de468052e95d223a08694fa709e94fcc8465289469c8c9f0111885c5191b7d0340370d58b6037b761dce9fc8ef914a47abac9bd08
+  data.tar.gz: 194f43bfefd4a7f60988efa6a35683108a8250e864105b6c9ac12a7d9674e0fde2a03fe6a29a678fa8c05624c871346627bf93efa5985552a33ad05ffe37e694

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlagKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,196 @@
+# FlagKit Ruby SDK
+
+Official Ruby SDK for [FlagKit](https://flagkit.dev) feature flag management.
+
+## Requirements
+
+- Ruby 3.0+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'flagkit'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install flagkit
+```
+
+## Quick Start
+
+```ruby
+require 'flagkit'
+
+# Initialize the SDK
+client = FlagKit.initialize('sdk_your_api_key')
+
+# Identify the current user
+FlagKit.identify('user-123', plan: 'pro')
+
+# Evaluate feature flags
+dark_mode = FlagKit.get_boolean_value('dark-mode', false)
+theme = FlagKit.get_string_value('theme', 'light')
+max_items = FlagKit.get_number_value('max-items', 10)
+config = FlagKit.get_json_value('feature-config', {})
+
+# Track events
+FlagKit.track('button_clicked', button: 'signup')
+
+# Shutdown when done
+FlagKit.shutdown
+```
+
+## Features
+
+- **Type-safe evaluation** - Boolean, string, number, and JSON flag types
+- **Local caching** - Fast evaluations with configurable TTL and optional encryption
+- **Background polling** - Automatic flag updates
+- **Event tracking** - Analytics with batching and crash-resilient persistence
+- **Resilient** - Circuit breaker, retry with exponential backoff, offline support
+- **Thread-safe** - Safe for concurrent use
+- **Security** - PII detection, request signing, bootstrap verification, timing attack protection
+
+## Configuration Options
+
+```ruby
+client = FlagKit.initialize(
+  'sdk_your_api_key',
+  polling_interval: 30,                         # Seconds between polls
+  cache_ttl: 300,                               # Cache time-to-live in seconds
+  cache_enabled: true,                          # Enable/disable caching
+  events_enabled: true,                         # Enable/disable event tracking
+  event_batch_size: 10,                         # Events per batch
+  event_flush_interval: 30,                     # Seconds between flushes
+  timeout: 10,                                  # Request timeout in seconds
+  retry_attempts: 3,                            # Number of retry attempts
+  circuit_breaker_threshold: 5,                 # Failures before circuit opens
+  circuit_breaker_reset_timeout: 30,            # Seconds before half-open
+  local_port: nil                               # Local dev server port (uses http://localhost:{port}/api/v1)
+)
+```
+
+Security features such as PII detection, request signing, bootstrap verification, cache encryption, evaluation jitter, and error sanitization are also available as configuration options.
+
+## Local Development
+
+For local development, use the `local_port` option to connect to a local FlagKit server:
+
+```ruby
+client = FlagKit.initialize(
+  'sdk_your_api_key',
+  local_port: 8200  # Uses http://localhost:8200/api/v1
+)
+```
+
+## Using the Client Directly
+
+```ruby
+client = FlagKit::Client.new(
+  FlagKit::Options.new(api_key: 'sdk_your_api_key')
+)
+client.initialize_sdk
+
+# Wait for initialization
+client.wait_for_ready(timeout: 5)
+
+# Evaluate flags
+result = client.evaluate('my-feature', false)
+puts result.value
+puts result.reason
+puts result.version
+
+# Clean up
+client.close
+```
+
+## Evaluation Context
+
+```ruby
+# Build a context
+context = FlagKit::EvaluationContext.new(
+  user_id: 'user-123',
+  email: 'user@example.com',
+  plan: 'enterprise'
+)
+
+# Use with evaluation
+value = FlagKit.get_boolean_value('premium-feature', false, context: context)
+
+# Private attributes (stripped before sending to server)
+context = FlagKit::EvaluationContext.new(
+  user_id: 'user-123',
+  _internal_id: 'hidden'  # Underscore prefix = private
+)
+```
+
+## Error Handling
+
+```ruby
+begin
+  FlagKit.initialize('invalid_key')
+rescue FlagKit::Error => e
+  puts "Error code: #{e.code}"
+  puts "Message: #{e.message}"
+  puts "Recoverable: #{e.recoverable?}"
+end
+```
+
+## API Reference
+
+### Module Methods
+
+| Method | Description |
+|--------|-------------|
+| `FlagKit.initialize(api_key, **options)` | Initialize the SDK |
+| `FlagKit.shutdown` | Shutdown and release resources |
+| `FlagKit.initialized?` | Check if SDK is initialized |
+| `FlagKit.identify(user_id, **attributes)` | Set user context |
+| `FlagKit.reset_context` | Clear user context |
+| `FlagKit.get_boolean_value(key, default, context:)` | Get boolean flag |
+| `FlagKit.get_string_value(key, default, context:)` | Get string flag |
+| `FlagKit.get_number_value(key, default, context:)` | Get number flag |
+| `FlagKit.get_json_value(key, default, context:)` | Get JSON flag |
+| `FlagKit.evaluate(key, default, context:)` | Get full evaluation result |
+| `FlagKit.track(event_type, data)` | Track analytics event |
+
+### Client Methods
+
+| Method | Description |
+|--------|-------------|
+| `client.initialize_sdk` | Initialize and fetch flags |
+| `client.wait_for_ready(timeout:)` | Wait for initialization |
+| `client.ready?` | Check if ready |
+| `client.identify(user_id, **attributes)` | Set user context |
+| `client.reset_context` | Clear user context |
+| `client.context` | Get current context |
+| `client.evaluate(key, default, context:)` | Evaluate a flag |
+| `client.get_boolean_value(key, default, context:)` | Get boolean value |
+| `client.get_string_value(key, default, context:)` | Get string value |
+| `client.get_number_value(key, default, context:)` | Get number value |
+| `client.get_int_value(key, default, context:)` | Get integer value |
+| `client.get_json_value(key, default, context:)` | Get JSON value |
+| `client.track(event_type, data)` | Track an event |
+| `client.close` | Close and release resources |
+
+## Thread Safety
+
+All SDK methods are safe for concurrent use from multiple threads. The client uses internal synchronization (Mutex) to ensure thread-safe access to:
+
+- Flag cache
+- Event queue
+- Context management
+- Polling state
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

data/lib/flagkit/client.rb

@@ -0,0 +1,443 @@
+# frozen_string_literal: true
+
+module FlagKit
+  # The main FlagKit client for evaluating feature flags.
+  class Client
+    attr_reader :options, :ready
+
+    # @param options [Options] The client options
+    def initialize(options)
+      @options = options
+      @ready = false
+      @ready_mutex = Mutex.new
+      @ready_condition = ConditionVariable.new
+      @context = EvaluationContext.new
+      @context_mutex = Mutex.new
+
+      setup_components
+    end
+
+    # Initializes the SDK by fetching initial flag state.
+    def initialize_sdk
+      load_bootstrap if options.bootstrap
+      fetch_initial_flags
+      start_background_tasks
+      mark_ready
+    rescue StandardError => e
+      log(:error, "Failed to initialize SDK: #{e.message}")
+      mark_ready
+      raise Error.init_error("Failed to initialize: #{e.message}")
+    end
+
+    # Waits for the SDK to be ready.
+    #
+    # @param timeout [Integer, nil] Maximum time to wait in seconds
+    # @return [Boolean] Whether the SDK is ready
+    def wait_for_ready(timeout: nil)
+      @ready_mutex.synchronize do
+        return true if @ready
+
+        timeout ? @ready_condition.wait(@ready_mutex, timeout) : wait_until_ready
+        @ready
+      end
+    end
+
+    # Checks if the SDK is ready.
+    #
+    # @return [Boolean]
+    def ready?
+      @ready_mutex.synchronize { @ready }
+    end
+
+    # Sets the user context.
+    #
+    # @param user_id [String] The user ID
+    # @param attributes [Hash] User attributes
+    def identify(user_id, **attributes)
+      @context_mutex.synchronize do
+        @context = EvaluationContext.new(user_id: user_id, **attributes)
+      end
+    end
+
+    # Clears the user context.
+    def reset_context
+      @context_mutex.synchronize { @context = EvaluationContext.new }
+    end
+
+    # Gets the current context.
+    #
+    # @return [EvaluationContext]
+    def context
+      @context_mutex.synchronize { @context.dup }
+    end
+
+    # Evaluates a flag and returns the full result.
+    #
+    # @param key [String] The flag key
+    # @param default_value [Object] The default value
+    # @param context [EvaluationContext, nil] Optional context override
+    # @return [EvaluationResult]
+    def evaluate(key, default_value, context: nil)
+      apply_evaluation_jitter
+      cached_result = try_cached_evaluation(key)
+      return cached_result if cached_result
+
+      fetch_and_cache_flag(key, merge_context(context), default_value)
+    end
+
+    # Gets a boolean flag value.
+    #
+    # @param key [String] The flag key
+    # @param default_value [Boolean] The default value
+    # @param context [EvaluationContext, nil] Optional context override
+    # @return [Boolean]
+    def get_boolean_value(key, default_value, context: nil)
+      evaluate(key, default_value, context: context).boolean_value
+    end
+
+    # Gets a string flag value.
+    #
+    # @param key [String] The flag key
+    # @param default_value [String] The default value
+    # @param context [EvaluationContext, nil] Optional context override
+    # @return [String, nil]
+    def get_string_value(key, default_value, context: nil)
+      evaluate(key, default_value, context: context).string_value || default_value
+    end
+
+    # Gets a number flag value.
+    #
+    # @param key [String] The flag key
+    # @param default_value [Float] The default value
+    # @param context [EvaluationContext, nil] Optional context override
+    # @return [Float]
+    def get_number_value(key, default_value, context: nil)
+      evaluate(key, default_value, context: context).number_value
+    end
+
+    # Gets an integer flag value.
+    #
+    # @param key [String] The flag key
+    # @param default_value [Integer] The default value
+    # @param context [EvaluationContext, nil] Optional context override
+    # @return [Integer]
+    def get_int_value(key, default_value, context: nil)
+      evaluate(key, default_value, context: context).int_value
+    end
+
+    # Gets a JSON flag value.
+    #
+    # @param key [String] The flag key
+    # @param default_value [Hash] The default value
+    # @param context [EvaluationContext, nil] Optional context override
+    # @return [Hash, nil]
+    def get_json_value(key, default_value, context: nil)
+      evaluate(key, default_value, context: context).json_value || default_value
+    end
+
+    # Checks if a flag exists in the cache.
+    #
+    # @param key [String] The flag key
+    # @return [Boolean]
+    def has_flag?(key)
+      return false unless options.cache_enabled
+
+      @cache.has?(key)
+    end
+
+    # Returns all cached flag keys.
+    #
+    # @return [Array<String>]
+    def get_all_flag_keys
+      return [] unless options.cache_enabled
+
+      @cache.keys
+    end
+
+    # Evaluates all cached flags and returns results.
+    #
+    # @param context [EvaluationContext, nil] Optional context override
+    # @return [Hash<String, EvaluationResult>]
+    def evaluate_all(context: nil)
+      return {} unless options.cache_enabled
+
+      results = {}
+      @cache.keys.each do |key|
+        cached = @cache.get(key)
+        results[key] = build_result(key, cached, EvaluationReason::CACHED) if cached
+      end
+      results
+    end
+
+    # Tracks an analytics event.
+    #
+    # @param event_type [String] The event type
+    # @param data [Hash, nil] Optional event data
+    def track(event_type, data = nil)
+      return unless options.events_enabled && @event_queue
+
+      @event_queue.enqueue(build_event(event_type, data))
+    end
+
+    # Closes the client and releases resources.
+    def close
+      @polling_manager.stop
+      @event_queue&.stop
+      @cache.clear
+      log(:info, 'Client closed')
+    end
+
+    private
+
+    def setup_components
+      @circuit_breaker = build_circuit_breaker
+      @http_client = build_http_client
+      @cache = build_cache
+      @polling_manager = build_polling_manager
+      @event_queue = build_event_queue if options.events_enabled
+    end
+
+    def build_circuit_breaker
+      CircuitBreaker.new(
+        failure_threshold: options.circuit_breaker_threshold,
+        reset_timeout: options.circuit_breaker_reset_timeout
+      )
+    end
+
+    def build_http_client
+      HttpClient.new(
+        api_key: options.api_key, timeout: options.timeout,
+        retry_attempts: options.retry_attempts, circuit_breaker: @circuit_breaker,
+        logger: options.logger, secondary_api_key: options.secondary_api_key,
+        key_rotation_grace_period: options.key_rotation_grace_period,
+        enable_request_signing: options.enable_request_signing
+      )
+    end
+
+    def build_cache
+      return build_encrypted_cache if options.encrypt_cache
+
+      Cache.new(ttl: options.cache_ttl, max_size: options.max_cache_size)
+    end
+
+    def build_encrypted_cache
+      EncryptedCache.new(
+        api_key: options.api_key, ttl: options.cache_ttl,
+        max_size: options.max_cache_size, logger: options.logger
+      )
+    end
+
+    def build_polling_manager
+      PollingManager.new(
+        interval: options.polling_interval,
+        on_update: method(:poll_for_updates),
+        logger: options.logger
+      )
+    end
+
+    def build_event_queue
+      EventQueue.new(
+        batch_size: options.event_batch_size,
+        flush_interval: options.event_flush_interval,
+        on_flush: method(:send_events),
+        logger: options.logger
+      )
+    end
+
+    def mark_ready
+      @ready_mutex.synchronize do
+        @ready = true
+        @ready_condition.broadcast
+      end
+    end
+
+    def wait_until_ready
+      @ready_condition.wait(@ready_mutex) until @ready
+    end
+
+    def try_cached_evaluation(key)
+      return nil unless options.cache_enabled
+
+      cached = @cache.get(key)
+      cached ? build_result(key, cached, EvaluationReason::CACHED) : nil
+    end
+
+    def fetch_and_cache_flag(key, effective_context, default_value)
+      response = @http_client.post('/sdk/evaluate', {
+                                     key: key, context: effective_context.strip_private_attributes.to_h
+                                   })
+      flag_state = FlagState.from_hash(response)
+      cache_flag(key, flag_state) if options.cache_enabled
+      build_result(key, flag_state, EvaluationReason::SERVER)
+    rescue Error => e
+      log(:warn, "Evaluation failed for #{key}: #{e.message}")
+      EvaluationResult.default_result(key, default_value, EvaluationReason::ERROR)
+    end
+
+    def build_event(event_type, data)
+      {
+        type: event_type, timestamp: Time.now.utc.iso8601,
+        userId: context.user_id, data: data
+      }.compact
+    end
+
+    def load_bootstrap
+      return unless options.bootstrap.is_a?(Hash)
+
+      flags = extract_bootstrap_flags(options.bootstrap)
+      flags&.each { |flag_data| cache_flag(FlagState.from_hash(flag_data).key, FlagState.from_hash(flag_data)) }
+    end
+
+    def extract_bootstrap_flags(bootstrap)
+      return legacy_bootstrap_flags(bootstrap) unless bootstrap_has_flags_key?(bootstrap)
+
+      flags = bootstrap['flags'] || bootstrap[:flags] || []
+      return flags unless should_verify_bootstrap?(bootstrap)
+
+      verify_and_return_flags(bootstrap, flags)
+    end
+
+    def bootstrap_has_flags_key?(bootstrap)
+      bootstrap.key?('flags') || bootstrap.key?(:flags)
+    end
+
+    def should_verify_bootstrap?(bootstrap)
+      (bootstrap.key?('signature') || bootstrap.key?(:signature)) && options.bootstrap_verification_enabled
+    end
+
+    def legacy_bootstrap_flags(bootstrap)
+      bootstrap.is_a?(Array) ? bootstrap : []
+    end
+
+    def verify_and_return_flags(bootstrap, flags)
+      result = Utils::Security.verify_bootstrap_signature(
+        bootstrap, options.api_key, max_age_ms: options.bootstrap_verification_max_age
+      )
+      return flags if result[:valid]
+
+      handle_bootstrap_verification_failure(result[:error])
+      options.bootstrap_verification_on_failure == 'error' ? nil : flags
+    end
+
+    def handle_bootstrap_verification_failure(error_message)
+      return raise_bootstrap_error(error_message) if options.bootstrap_verification_on_failure == 'error'
+
+      log_bootstrap_warning(error_message) unless options.bootstrap_verification_on_failure == 'ignore'
+    end
+
+    def raise_bootstrap_error(error_message)
+      raise Error.config_error(ErrorCode::CONFIG_INVALID_BOOTSTRAP, "Bootstrap verification failed: #{error_message}")
+    end
+
+    def log_bootstrap_warning(error_message)
+      log(:warn, "Bootstrap verification failed: #{error_message}. Using bootstrap data anyway.")
+    end
+
+    def fetch_initial_flags
+      response = @http_client.get('/sdk/init')
+      process_flags_response(response)
+      check_version_metadata(response)
+    rescue Error => e
+      log(:warn, "Failed to fetch initial flags: #{e.message}")
+    end
+
+    # Check SDK version metadata from init response and emit appropriate warnings.
+    #
+    # Per spec, the SDK should parse and surface:
+    # - sdkVersionMin: Minimum required version (older may not work)
+    # - sdkVersionRecommended: Recommended version for optimal experience
+    # - sdkVersionLatest: Latest available version
+    # - deprecationWarning: Server-provided deprecation message
+    #
+    # @param response [Hash] The init response
+    def check_version_metadata(response)
+      metadata = response['metadata'] || response[:metadata]
+      return unless metadata
+
+      current_version = VERSION
+
+      # Check for server-provided deprecation warning first
+      deprecation_warning = metadata['deprecationWarning'] || metadata[:deprecationWarning]
+      if deprecation_warning && !deprecation_warning.empty?
+        log(:warn, "Deprecation Warning: #{deprecation_warning}")
+      end
+
+      # Check minimum version requirement
+      sdk_version_min = metadata['sdkVersionMin'] || metadata[:sdkVersionMin]
+      if sdk_version_min && Utils::Version.less_than?(current_version, sdk_version_min)
+        log(:error, "SDK version #{current_version} is below minimum required version #{sdk_version_min}. " \
+                    "Some features may not work correctly. Please upgrade the SDK.")
+      end
+
+      # Check recommended version
+      sdk_version_recommended = metadata['sdkVersionRecommended'] || metadata[:sdkVersionRecommended]
+      warned_about_recommended = false
+      if sdk_version_recommended && Utils::Version.less_than?(current_version, sdk_version_recommended)
+        log(:warn, "SDK version #{current_version} is below recommended version #{sdk_version_recommended}. " \
+                   "Consider upgrading for the best experience.")
+        warned_about_recommended = true
+      end
+
+      # Log if a newer version is available (info level, not a warning)
+      # Only log if we haven't already warned about recommended
+      sdk_version_latest = metadata['sdkVersionLatest'] || metadata[:sdkVersionLatest]
+      if sdk_version_latest &&
+         Utils::Version.less_than?(current_version, sdk_version_latest) &&
+         !warned_about_recommended
+        log(:info, "SDK version #{current_version} - a newer version #{sdk_version_latest} is available.")
+      end
+    end
+
+    def start_background_tasks
+      @polling_manager.start
+      @event_queue&.start
+    end
+
+    def poll_for_updates(last_update_time)
+      params = last_update_time ? { since: last_update_time.utc.iso8601 } : {}
+      process_flags_response(@http_client.get('/sdk/updates', params))
+    end
+
+    def process_flags_response(response)
+      (response['flags'] || []).each do |flag_data|
+        cache_flag(FlagState.from_hash(flag_data).key, FlagState.from_hash(flag_data))
+      end
+    end
+
+    def send_events(events)
+      @http_client.post('/sdk/events/batch', { events: events })
+    end
+
+    def merge_context(override_context)
+      current = @context_mutex.synchronize { @context }
+      override_context ? current.merge(override_context) : current
+    end
+
+    def get_cached_flag(key)
+      return nil unless options.cache_enabled
+
+      @cache.get(key)
+    end
+
+    def cache_flag(key, flag)
+      @cache.set(key, flag) if options.cache_enabled
+    end
+
+    def build_result(key, flag_state, reason)
+      EvaluationResult.new(
+        flag_key: key, value: flag_state.value, enabled: flag_state.enabled,
+        reason: reason, version: flag_state.version
+      )
+    end
+
+    def log(level, message)
+      options.logger&.send(level, "[FlagKit::Client] #{message}")
+    end
+
+    def apply_evaluation_jitter
+      return unless options.evaluation_jitter_enabled
+
+      sleep(rand(options.evaluation_jitter_min_ms..options.evaluation_jitter_max_ms) / 1000.0)
+    end
+  end
+end