flagkit 1.0.1

data/lib/flagkit/options.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module FlagKit
+  # Configuration options for the FlagKit SDK.
+  class Options
+    DEFAULT_POLLING_INTERVAL = 30
+    DEFAULT_CACHE_TTL = 300
+    DEFAULT_MAX_CACHE_SIZE = 1000
+    DEFAULT_EVENT_BATCH_SIZE = 10
+    DEFAULT_EVENT_FLUSH_INTERVAL = 30
+    DEFAULT_TIMEOUT = 10
+    DEFAULT_RETRY_ATTEMPTS = 3
+    DEFAULT_CIRCUIT_BREAKER_THRESHOLD = 5
+    DEFAULT_CIRCUIT_BREAKER_RESET_TIMEOUT = 30
+    DEFAULT_KEY_ROTATION_GRACE_PERIOD = 300
+    DEFAULT_MAX_PERSISTED_EVENTS = 10_000
+    DEFAULT_PERSISTENCE_FLUSH_INTERVAL = 1000
+    DEFAULT_EVALUATION_JITTER_ENABLED = false
+    DEFAULT_EVALUATION_JITTER_MIN_MS = 5
+    DEFAULT_EVALUATION_JITTER_MAX_MS = 15
+    DEFAULT_BOOTSTRAP_VERIFICATION_ENABLED = true
+    DEFAULT_BOOTSTRAP_VERIFICATION_MAX_AGE = 86_400_000 # 24 hours in milliseconds
+    DEFAULT_BOOTSTRAP_VERIFICATION_ON_FAILURE = "warn"
+    DEFAULT_ERROR_SANITIZATION_ENABLED = true
+    DEFAULT_ERROR_SANITIZATION_PRESERVE_ORIGINAL = false
+
+    attr_reader :api_key,
+                :polling_interval,
+                :cache_ttl,
+                :max_cache_size,
+                :cache_enabled,
+                :event_batch_size,
+                :event_flush_interval,
+                :events_enabled,
+                :timeout,
+                :retry_attempts,
+                :circuit_breaker_threshold,
+                :circuit_breaker_reset_timeout,
+                :bootstrap,
+                :logger,
+                :storage,
+                :local_port,
+                :secondary_api_key,
+                :key_rotation_grace_period,
+                :strict_pii_mode,
+                :enable_request_signing,
+                :encrypt_cache,
+                :persist_events,
+                :event_storage_path,
+                :max_persisted_events,
+                :persistence_flush_interval,
+                :evaluation_jitter_enabled,
+                :evaluation_jitter_min_ms,
+                :evaluation_jitter_max_ms,
+                :bootstrap_verification_enabled,
+                :bootstrap_verification_max_age,
+                :bootstrap_verification_on_failure,
+                :error_sanitization_enabled,
+                :error_sanitization_preserve_original,
+                :on_usage_update,
+                :on_subscription_error,
+                :on_connection_limit_error
+
+    # @param api_key [String] The API key
+    # @param polling_interval [Integer] Polling interval in seconds
+    # @param cache_ttl [Integer] Cache TTL in seconds
+    # @param max_cache_size [Integer] Maximum cache size
+    # @param cache_enabled [Boolean] Whether caching is enabled
+    # @param event_batch_size [Integer] Event batch size
+    # @param event_flush_interval [Integer] Event flush interval in seconds
+    # @param events_enabled [Boolean] Whether events are enabled
+    # @param timeout [Integer] Request timeout in seconds
+    # @param retry_attempts [Integer] Number of retry attempts
+    # @param circuit_breaker_threshold [Integer] Circuit breaker failure threshold
+    # @param circuit_breaker_reset_timeout [Integer] Circuit breaker reset timeout in seconds
+    # @param bootstrap [Hash, nil] Bootstrap data
+    # @param logger [Object, nil] Logger instance
+    # @param storage [Object, nil] Storage adapter
+    # @param local_port [Integer, nil] Local development server port (uses http://localhost:{port}/api/v1)
+    # @param secondary_api_key [String, nil] Secondary API key for key rotation
+    # @param key_rotation_grace_period [Integer] Grace period in seconds during key rotation
+    # @param strict_pii_mode [Boolean] Raise SecurityError instead of warning when PII detected
+    # @param enable_request_signing [Boolean] Enable HMAC-SHA256 request signing for POST requests
+    # @param encrypt_cache [Boolean] Enable AES-256-GCM encryption for cached data
+    # @param persist_events [Boolean] Enable crash-resilient event persistence
+    # @param event_storage_path [String, nil] Directory for event storage (defaults to OS temp dir)
+    # @param max_persisted_events [Integer] Maximum events to persist
+    # @param persistence_flush_interval [Integer] Milliseconds between disk writes
+    # @param evaluation_jitter_enabled [Boolean] Enable timing jitter for cache timing attack protection
+    # @param evaluation_jitter_min_ms [Integer] Minimum jitter delay in milliseconds
+    # @param evaluation_jitter_max_ms [Integer] Maximum jitter delay in milliseconds
+    # @param bootstrap_verification_enabled [Boolean] Enable HMAC-SHA256 signature verification for bootstrap data
+    # @param bootstrap_verification_max_age [Integer] Maximum age in milliseconds for bootstrap data
+    # @param bootstrap_verification_on_failure [String] Action on verification failure: 'warn', 'error', or 'ignore'
+    # @param error_sanitization_enabled [Boolean] Enable sanitization of sensitive info from error messages
+    # @param error_sanitization_preserve_original [Boolean] Preserve original message in addition to sanitized
+    # @param on_usage_update [Proc, nil] Callback for usage metrics updates (receives UsageMetrics)
+    # @param on_subscription_error [Proc, nil] Callback when subscription error occurs in streaming (receives message)
+    # @param on_connection_limit_error [Proc, nil] Callback when connection limit is reached in streaming
+    def initialize(
+      api_key:,
+      polling_interval: DEFAULT_POLLING_INTERVAL,
+      cache_ttl: DEFAULT_CACHE_TTL,
+      max_cache_size: DEFAULT_MAX_CACHE_SIZE,
+      cache_enabled: true,
+      event_batch_size: DEFAULT_EVENT_BATCH_SIZE,
+      event_flush_interval: DEFAULT_EVENT_FLUSH_INTERVAL,
+      events_enabled: true,
+      timeout: DEFAULT_TIMEOUT,
+      retry_attempts: DEFAULT_RETRY_ATTEMPTS,
+      circuit_breaker_threshold: DEFAULT_CIRCUIT_BREAKER_THRESHOLD,
+      circuit_breaker_reset_timeout: DEFAULT_CIRCUIT_BREAKER_RESET_TIMEOUT,
+      bootstrap: nil,
+      logger: nil,
+      storage: nil,
+      local_port: nil,
+      secondary_api_key: nil,
+      key_rotation_grace_period: DEFAULT_KEY_ROTATION_GRACE_PERIOD,
+      strict_pii_mode: false,
+      enable_request_signing: true,
+      encrypt_cache: false,
+      persist_events: false,
+      event_storage_path: nil,
+      max_persisted_events: DEFAULT_MAX_PERSISTED_EVENTS,
+      persistence_flush_interval: DEFAULT_PERSISTENCE_FLUSH_INTERVAL,
+      evaluation_jitter_enabled: DEFAULT_EVALUATION_JITTER_ENABLED,
+      evaluation_jitter_min_ms: DEFAULT_EVALUATION_JITTER_MIN_MS,
+      evaluation_jitter_max_ms: DEFAULT_EVALUATION_JITTER_MAX_MS,
+      bootstrap_verification_enabled: DEFAULT_BOOTSTRAP_VERIFICATION_ENABLED,
+      bootstrap_verification_max_age: DEFAULT_BOOTSTRAP_VERIFICATION_MAX_AGE,
+      bootstrap_verification_on_failure: DEFAULT_BOOTSTRAP_VERIFICATION_ON_FAILURE,
+      error_sanitization_enabled: DEFAULT_ERROR_SANITIZATION_ENABLED,
+      error_sanitization_preserve_original: DEFAULT_ERROR_SANITIZATION_PRESERVE_ORIGINAL,
+      on_usage_update: nil,
+      on_subscription_error: nil,
+      on_connection_limit_error: nil
+    )
+      @api_key = api_key
+      @polling_interval = polling_interval
+      @cache_ttl = cache_ttl
+      @max_cache_size = max_cache_size
+      @cache_enabled = cache_enabled
+      @event_batch_size = event_batch_size
+      @event_flush_interval = event_flush_interval
+      @events_enabled = events_enabled
+      @timeout = timeout
+      @retry_attempts = retry_attempts
+      @circuit_breaker_threshold = circuit_breaker_threshold
+      @circuit_breaker_reset_timeout = circuit_breaker_reset_timeout
+      @bootstrap = bootstrap
+      @logger = logger
+      @storage = storage
+      @local_port = local_port
+      @secondary_api_key = secondary_api_key
+      @key_rotation_grace_period = key_rotation_grace_period
+      @strict_pii_mode = strict_pii_mode
+      @enable_request_signing = enable_request_signing
+      @encrypt_cache = encrypt_cache
+      @persist_events = persist_events
+      @event_storage_path = event_storage_path || default_event_storage_path
+      @max_persisted_events = max_persisted_events
+      @persistence_flush_interval = persistence_flush_interval
+      @evaluation_jitter_enabled = evaluation_jitter_enabled
+      @evaluation_jitter_min_ms = evaluation_jitter_min_ms
+      @evaluation_jitter_max_ms = evaluation_jitter_max_ms
+      @bootstrap_verification_enabled = bootstrap_verification_enabled
+      @bootstrap_verification_max_age = bootstrap_verification_max_age
+      @bootstrap_verification_on_failure = bootstrap_verification_on_failure
+      @error_sanitization_enabled = error_sanitization_enabled
+      @error_sanitization_preserve_original = error_sanitization_preserve_original
+      @on_usage_update = on_usage_update
+      @on_subscription_error = on_subscription_error
+      @on_connection_limit_error = on_connection_limit_error
+    end
+
+    # Validates the options.
+    #
+    # @raise [Error] If validation fails
+    # @raise [SecurityError] If local_port is used in production
+    def validate!
+      validate_api_key!
+      validate_positive_integers!
+      validate_local_port_restriction!
+    end
+
+    private
+
+    def validate_local_port_restriction!
+      return unless local_port
+
+      env = ENV.fetch("RACK_ENV", ENV.fetch("RAILS_ENV", nil))
+      return unless env == "production"
+
+      raise SecurityError.new(
+        ErrorCode::SECURITY_LOCAL_PORT_IN_PRODUCTION,
+        "local_port cannot be used in production environment. " \
+        "This is a security risk as it bypasses HTTPS and may expose traffic to interception."
+      )
+    end
+
+    def validate_api_key!
+      raise Error.config_error(ErrorCode::CONFIG_INVALID_API_KEY, "API key is required") if api_key.nil? || api_key.empty?
+
+      unless api_key.start_with?("sdk_", "srv_", "cli_")
+        raise Error.config_error(ErrorCode::CONFIG_INVALID_API_KEY, "Invalid API key format")
+      end
+    end
+
+    def validate_positive_integers!
+      if polling_interval <= 0
+        raise Error.config_error(ErrorCode::CONFIG_INVALID_POLLING_INTERVAL, "Polling interval must be positive")
+      end
+
+      raise Error.config_error(ErrorCode::CONFIG_INVALID_CACHE_TTL, "Cache TTL must be positive") if cache_ttl <= 0
+    end
+
+    def default_event_storage_path
+      require "tmpdir"
+      File.join(Dir.tmpdir, "flagkit", "events")
+    end
+  end
+end

data/lib/flagkit/types/evaluation_context.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module FlagKit
+  module Types
+    # Context for flag evaluation containing user and custom attributes.
+    class EvaluationContext
+      PRIVATE_ATTRIBUTE_PREFIX = "_"
+
+      attr_reader :user_id, :attributes
+
+      # @param user_id [String, nil] The user identifier
+      # @param attributes [Hash] Custom attributes
+      def initialize(user_id: nil, **attributes)
+        @user_id = user_id
+        @attributes = attributes.transform_keys(&:to_s)
+      end
+
+      # Creates a new context with the given user ID.
+      #
+      # @param user_id [String] The user ID
+      # @return [EvaluationContext]
+      def with_user_id(user_id)
+        self.class.new(user_id: user_id, **attributes)
+      end
+
+      # Creates a new context with the given attribute added.
+      #
+      # @param key [String, Symbol] The attribute key
+      # @param value [Object] The attribute value
+      # @return [EvaluationContext]
+      def with_attribute(key, value)
+        new_attrs = attributes.merge(key.to_s => value)
+        self.class.new(user_id: user_id, **new_attrs)
+      end
+
+      # Creates a new context with multiple attributes added.
+      #
+      # @param attrs [Hash] The attributes to add
+      # @return [EvaluationContext]
+      def with_attributes(attrs)
+        new_attrs = attributes.merge(attrs.transform_keys(&:to_s))
+        self.class.new(user_id: user_id, **new_attrs)
+      end
+
+      # Merges another context into this one.
+      # The other context takes precedence.
+      #
+      # @param other [EvaluationContext, nil] The other context
+      # @return [EvaluationContext]
+      def merge(other)
+        return self unless other
+
+        new_user_id = other.user_id || user_id
+        new_attrs = attributes.merge(other.attributes)
+        self.class.new(user_id: new_user_id, **new_attrs)
+      end
+
+      # Creates a copy with private attributes stripped.
+      #
+      # @return [EvaluationContext]
+      def strip_private_attributes
+        public_attrs = attributes.reject { |key, _| key.start_with?(PRIVATE_ATTRIBUTE_PREFIX) }
+        self.class.new(user_id: user_id, **public_attrs)
+      end
+
+      # Checks if the context is empty.
+      #
+      # @return [Boolean]
+      def empty?
+        user_id.nil? && attributes.empty?
+      end
+
+      # Gets an attribute value.
+      #
+      # @param key [String, Symbol] The attribute key
+      # @return [Object, nil]
+      def [](key)
+        attributes[key.to_s]
+      end
+
+      # Converts the context to a hash for API requests.
+      #
+      # @return [Hash]
+      def to_h
+        result = {}
+        result["userId"] = user_id if user_id
+        result["attributes"] = attributes unless attributes.empty?
+        result
+      end
+
+      # Creates a context from a hash.
+      #
+      # @param data [Hash] The data hash
+      # @return [EvaluationContext]
+      def self.from_hash(data)
+        return new if data.nil?
+
+        user_id = data["userId"] || data["user_id"] || data[:user_id]
+        attrs = data["attributes"] || data[:attributes] || {}
+        new(user_id: user_id, **attrs)
+      end
+
+      def ==(other)
+        return false unless other.is_a?(EvaluationContext)
+
+        user_id == other.user_id && attributes == other.attributes
+      end
+
+      def eql?(other)
+        self == other
+      end
+
+      def hash
+        [user_id, attributes].hash
+      end
+    end
+  end
+
+  # Alias for backward compatibility
+  EvaluationContext = Types::EvaluationContext
+end

data/lib/flagkit/types/evaluation_reason.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module FlagKit
+  module Types
+    # Reasons for flag evaluation results.
+    module EvaluationReason
+      CACHED = "CACHED"
+      DEFAULT = "DEFAULT"
+      FLAG_NOT_FOUND = "FLAG_NOT_FOUND"
+      BOOTSTRAP = "BOOTSTRAP"
+      SERVER = "SERVER"
+      STALE_CACHE = "STALE_CACHE"
+      ERROR = "ERROR"
+      DISABLED = "DISABLED"
+      TYPE_MISMATCH = "TYPE_MISMATCH"
+      OFFLINE = "OFFLINE"
+    end
+  end
+
+  # Alias for backward compatibility
+  EvaluationReason = Types::EvaluationReason
+end

data/lib/flagkit/types/evaluation_result.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module FlagKit
+  module Types
+    # Result of evaluating a feature flag.
+    class EvaluationResult
+      attr_reader :flag_key, :value, :enabled, :reason, :version, :timestamp
+
+      # @param flag_key [String] The flag key
+      # @param value [Object] The evaluated value
+      # @param enabled [Boolean] Whether the flag is enabled
+      # @param reason [String] The evaluation reason
+      # @param version [Integer] The flag version
+      # @param timestamp [Time] When the evaluation occurred
+      def initialize(flag_key:, value:, enabled: false, reason: EvaluationReason::DEFAULT, version: 0, timestamp: nil)
+        @flag_key = flag_key
+        @value = value
+        @enabled = enabled
+        @reason = reason
+        @version = version
+        @timestamp = timestamp || Time.now
+      end
+
+      # @return [Boolean] The value as a boolean
+      def boolean_value
+        value == true
+      end
+
+      # @return [String, nil] The value as a string
+      def string_value
+        value&.to_s
+      end
+
+      # @return [Float] The value as a float
+      def number_value
+        value.is_a?(Numeric) ? value.to_f : 0.0
+      end
+
+      # @return [Integer] The value as an integer
+      def int_value
+        value.is_a?(Numeric) ? value.to_i : 0
+      end
+
+      # @return [Hash, nil] The value as a hash
+      def json_value
+        value.is_a?(Hash) ? value : nil
+      end
+
+      # Creates a default result.
+      #
+      # @param key [String] The flag key
+      # @param default_value [Object] The default value
+      # @param reason [String] The reason
+      # @return [EvaluationResult]
+      def self.default_result(key, default_value, reason)
+        new(flag_key: key, value: default_value, enabled: false, reason: reason)
+      end
+
+      # Converts the result to a hash.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          flag_key: flag_key,
+          value: value,
+          enabled: enabled,
+          reason: reason,
+          version: version,
+          timestamp: timestamp.iso8601
+        }
+      end
+    end
+  end
+
+  # Alias for backward compatibility
+  EvaluationResult = Types::EvaluationResult
+end

data/lib/flagkit/types/flag_state.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module FlagKit
+  module Types
+    # Represents the state of a feature flag.
+    class FlagState
+      attr_reader :key, :value, :enabled, :version, :flag_type, :last_modified, :metadata
+
+      # @param key [String] The flag key
+      # @param value [Object] The flag value
+      # @param enabled [Boolean] Whether the flag is enabled
+      # @param version [Integer] The flag version
+      # @param flag_type [String] The flag type
+      # @param last_modified [String, nil] ISO 8601 timestamp
+      # @param metadata [Hash, nil] Additional metadata
+      def initialize(key:, value:, enabled: true, version: 0, flag_type: nil, last_modified: nil, metadata: nil)
+        @key = key
+        @value = value
+        @enabled = enabled
+        @version = version
+        @flag_type = flag_type || FlagType.infer(value)
+        @last_modified = last_modified || Time.now.utc.iso8601
+        @metadata = metadata || {}
+      end
+
+      # @return [Boolean] The value as a boolean
+      def boolean_value
+        value == true
+      end
+
+      # @return [String, nil] The value as a string
+      def string_value
+        value&.to_s
+      end
+
+      # @return [Float] The value as a float
+      def number_value
+        value.is_a?(Numeric) ? value.to_f : 0.0
+      end
+
+      # @return [Integer] The value as an integer
+      def int_value
+        value.is_a?(Numeric) ? value.to_i : 0
+      end
+
+      # @return [Hash, nil] The value as a hash
+      def json_value
+        value.is_a?(Hash) ? value : nil
+      end
+
+      # Creates a FlagState from a hash.
+      #
+      # @param data [Hash] The data hash
+      # @return [FlagState]
+      def self.from_hash(data)
+        new(
+          key: data["key"] || data[:key],
+          value: data["value"] || data[:value],
+          enabled: data.fetch("enabled", data.fetch(:enabled, true)),
+          version: data["version"] || data[:version] || 0,
+          flag_type: data["flagType"] || data[:flag_type],
+          last_modified: data["lastModified"] || data[:last_modified],
+          metadata: data["metadata"] || data[:metadata]
+        )
+      end
+
+      # Converts the flag state to a hash.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          key: key,
+          value: value,
+          enabled: enabled,
+          version: version,
+          flag_type: flag_type,
+          last_modified: last_modified,
+          metadata: metadata
+        }
+      end
+
+      def ==(other)
+        return false unless other.is_a?(FlagState)
+
+        key == other.key && value == other.value && enabled == other.enabled && version == other.version
+      end
+
+      def eql?(other)
+        self == other
+      end
+
+      def hash
+        [key, value, enabled, version].hash
+      end
+    end
+  end
+
+  # Alias for backward compatibility
+  FlagState = Types::FlagState
+end

data/lib/flagkit/types/flag_type.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module FlagKit
+  module Types
+    # Types of feature flags.
+    module FlagType
+      BOOLEAN = "boolean"
+      STRING = "string"
+      NUMBER = "number"
+      JSON = "json"
+
+      ALL = [BOOLEAN, STRING, NUMBER, JSON].freeze
+
+      # Infers the flag type from a value.
+      #
+      # @param value [Object] The value to infer type from
+      # @return [String] The inferred flag type
+      def self.infer(value)
+        case value
+        when TrueClass, FalseClass
+          BOOLEAN
+        when String
+          STRING
+        when Numeric
+          NUMBER
+        else
+          JSON
+        end
+      end
+
+      # Parses a flag type string.
+      #
+      # @param value [String] The type string
+      # @return [String] The normalized flag type
+      def self.parse(value)
+        return JSON unless value
+
+        normalized = value.to_s.downcase
+        ALL.include?(normalized) ? normalized : JSON
+      end
+    end
+  end
+
+  # Alias for backward compatibility
+  FlagType = Types::FlagType
+end