flagkit 1.0.1

data/lib/flagkit/error/error_sanitizer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module FlagKit
+  # Sanitizes error messages to remove sensitive information.
+  #
+  # This utility removes potentially sensitive data from error messages
+  # to prevent information leakage in logs, error reports, and user-facing messages.
+  module ErrorSanitizer
+    # Patterns for sanitizing sensitive information.
+    # Each entry is [pattern, replacement].
+    PATTERNS = [
+      # Unix-style paths
+      [%r{/(?:[\w.-]+/)+[\w.-]+}, "[PATH]"],
+      # Windows-style paths
+      [/[A-Za-z]:\\(?:[\w.-]+\\)+[\w.-]*/, "[PATH]"],
+      # IP addresses
+      [/\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/, "[IP]"],
+      # SDK API keys
+      [/sdk_[a-zA-Z0-9_-]{8,}/, "sdk_[REDACTED]"],
+      # Server API keys
+      [/srv_[a-zA-Z0-9_-]{8,}/, "srv_[REDACTED]"],
+      # CLI API keys
+      [/cli_[a-zA-Z0-9_-]{8,}/, "cli_[REDACTED]"],
+      # Email addresses
+      [/[\w.-]+@[\w.-]+\.\w+/, "[EMAIL]"],
+      # Database connection strings
+      [%r{(?:postgres|mysql|mongodb|redis)://[^\s]+}i, "[CONNECTION_STRING]"]
+    ].freeze
+
+    class << self
+      # Sanitizes a message by removing sensitive information.
+      #
+      # @param message [String] The message to sanitize
+      # @param enabled [Boolean] Whether sanitization is enabled
+      # @return [String] The sanitized message
+      def sanitize(message, enabled: true)
+        return message unless enabled
+        return message if message.nil? || message.empty?
+
+        result = message.dup
+        PATTERNS.each do |pattern, replacement|
+          result.gsub!(pattern, replacement)
+        end
+        result
+      end
+    end
+  end
+end

data/lib/flagkit/error/flagkit_error.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module FlagKit
+  # Base exception for all FlagKit SDK errors.
+  class FlagKitError < StandardError
+    attr_reader :code, :details, :original_message
+
+    class << self
+      # @return [Boolean] Whether error sanitization is enabled
+      attr_accessor :sanitization_enabled
+
+      # @return [Boolean] Whether to preserve the original message
+      attr_accessor :preserve_original
+    end
+
+    # Default sanitization settings
+    @sanitization_enabled = true
+    @preserve_original = false
+
+    # @param code [String] The error code
+    # @param message [String] The error message
+    # @param cause [Exception, nil] The underlying cause
+    # @param sanitize [Boolean, nil] Override sanitization setting for this error
+    def initialize(code, message, cause: nil, sanitize: nil)
+      @code = code
+      @cause = cause
+      @details = {}
+
+      should_sanitize = sanitize.nil? ? self.class.sanitization_enabled : sanitize
+      sanitized_message = FlagKit::ErrorSanitizer.sanitize(message, enabled: should_sanitize)
+
+      @original_message = message if self.class.preserve_original && should_sanitize
+
+      super("[#{code}] #{sanitized_message}")
+    end
+
+    # @return [Boolean] Whether the error is recoverable
+    def recoverable?
+      ErrorCode.recoverable?(code)
+    end
+
+    # @return [Exception, nil] The underlying cause
+    def cause
+      @cause || super
+    end
+
+    # Adds details to the error.
+    #
+    # @param details [Hash] The details to add
+    # @return [self]
+    def with_details(details)
+      @details.merge!(details)
+      self
+    end
+
+    class << self
+      # Creates an initialization error.
+      def init_error(message)
+        new(ErrorCode::INIT_FAILED, message)
+      end
+
+      # Creates an authentication error.
+      def auth_error(code, message)
+        new(code, message)
+      end
+
+      # Creates a network error.
+      def network_error(message, cause: nil)
+        new(ErrorCode::NETWORK_ERROR, message, cause: cause)
+      end
+
+      # Creates an evaluation error.
+      def eval_error(code, message)
+        new(code, message)
+      end
+
+      # Creates a configuration error.
+      def config_error(code, message)
+        new(code, message)
+      end
+
+      # Creates a security error.
+      def security_error(code, message)
+        new(code, message)
+      end
+    end
+  end
+
+  # Alias for backward compatibility - use Error as the exception class name
+  Error = FlagKitError
+
+  # SecurityError for strict PII mode and other security violations
+  class SecurityError < FlagKitError
+  end
+end

data/lib/flagkit/http/circuit_breaker.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module FlagKit
+  module Http
+    # Circuit breaker pattern implementation for resilient HTTP calls.
+    class CircuitBreaker
+      # Circuit breaker states
+      module State
+        CLOSED = :closed
+        OPEN = :open
+        HALF_OPEN = :half_open
+      end
+
+      attr_reader :state, :failure_threshold, :reset_timeout
+
+      # @param failure_threshold [Integer] Number of failures before opening
+      # @param reset_timeout [Integer] Seconds to wait before half-open
+      def initialize(failure_threshold: 5, reset_timeout: 30)
+        @failure_threshold = failure_threshold
+        @reset_timeout = reset_timeout
+        @state = State::CLOSED
+        @failure_count = 0
+        @last_failure_time = nil
+        @mutex = Mutex.new
+      end
+
+      # Checks if the circuit allows requests.
+      #
+      # @return [Boolean]
+      def allow_request?
+        @mutex.synchronize do
+          case @state
+          when State::CLOSED
+            true
+          when State::OPEN
+            check_reset_timeout
+            @state != State::OPEN
+          when State::HALF_OPEN
+            true
+          end
+        end
+      end
+
+      # Records a successful request.
+      def record_success
+        @mutex.synchronize do
+          @failure_count = 0
+          @state = State::CLOSED
+        end
+      end
+
+      # Records a failed request.
+      def record_failure
+        @mutex.synchronize do
+          @failure_count += 1
+          @last_failure_time = Time.now
+
+          if @failure_count >= failure_threshold
+            @state = State::OPEN
+          end
+        end
+      end
+
+      # Checks if the circuit is open.
+      #
+      # @return [Boolean]
+      def open?
+        @mutex.synchronize do
+          check_reset_timeout
+          @state == State::OPEN
+        end
+      end
+
+      # Checks if the circuit is closed.
+      #
+      # @return [Boolean]
+      def closed?
+        @mutex.synchronize do
+          @state == State::CLOSED
+        end
+      end
+
+      # Checks if the circuit is half-open.
+      #
+      # @return [Boolean]
+      def half_open?
+        @mutex.synchronize do
+          check_reset_timeout
+          @state == State::HALF_OPEN
+        end
+      end
+
+      # Resets the circuit breaker to closed state.
+      def reset
+        @mutex.synchronize do
+          @state = State::CLOSED
+          @failure_count = 0
+          @last_failure_time = nil
+        end
+      end
+
+      # Returns the current failure count.
+      #
+      # @return [Integer]
+      def failure_count
+        @mutex.synchronize do
+          @failure_count
+        end
+      end
+
+      # Executes a block with circuit breaker protection.
+      #
+      # @yield The block to execute
+      # @return [Object] The block result
+      # @raise [Error] If the circuit is open
+      def call
+        unless allow_request?
+          raise FlagKit::Error.new(ErrorCode::CIRCUIT_OPEN, "Circuit breaker is open")
+        end
+
+        begin
+          result = yield
+          record_success
+          result
+        rescue StandardError => e
+          record_failure
+          raise e
+        end
+      end
+
+      private
+
+      def check_reset_timeout
+        return unless @state == State::OPEN && @last_failure_time
+
+        if Time.now - @last_failure_time >= reset_timeout
+          @state = State::HALF_OPEN
+        end
+      end
+    end
+  end
+
+  # Alias for backward compatibility
+  CircuitBreaker = Http::CircuitBreaker
+end

data/lib/flagkit/http/http_client.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module FlagKit
+  module Http
+    # Usage metrics extracted from response headers.
+    #
+    # Contains information about API usage limits and subscription status.
+    class UsageMetrics
+      # @return [Float, nil] Percentage of API call limit used this period (0-150+)
+      attr_reader :api_usage_percent
+
+      # @return [Float, nil] Percentage of evaluation limit used (0-150+)
+      attr_reader :evaluation_usage_percent
+
+      # @return [Boolean] Whether approaching rate limit threshold
+      attr_reader :rate_limit_warning
+
+      # @return [String, nil] Current subscription status: active, trial, past_due, suspended, cancelled
+      attr_reader :subscription_status
+
+      VALID_SUBSCRIPTION_STATUSES = %w[active trial past_due suspended cancelled].freeze
+
+      # @param api_usage_percent [Float, nil] API usage percentage
+      # @param evaluation_usage_percent [Float, nil] Evaluation usage percentage
+      # @param rate_limit_warning [Boolean] Rate limit warning flag
+      # @param subscription_status [String, nil] Subscription status
+      def initialize(api_usage_percent: nil, evaluation_usage_percent: nil, rate_limit_warning: false, subscription_status: nil)
+        @api_usage_percent = api_usage_percent
+        @evaluation_usage_percent = evaluation_usage_percent
+        @rate_limit_warning = rate_limit_warning
+        @subscription_status = subscription_status if subscription_status.nil? || VALID_SUBSCRIPTION_STATUSES.include?(subscription_status)
+      end
+    end
+
+    # HTTP client with retry logic, circuit breaker integration,
+    # request signing, and key rotation support.
+    class HttpClient
+      BASE_URL = "https://api.flagkit.dev/api/v1"
+      BASE_RETRY_DELAY = 1.0
+      MAX_RETRY_DELAY = 30.0
+      RETRY_MULTIPLIER = 2.0
+      JITTER_FACTOR = 0.1
+
+      attr_reader :timeout, :retry_attempts, :circuit_breaker
+
+      # Returns the base URL for the given local port, or the default production URL.
+      #
+      # @param local_port [Integer, nil] The local port number
+      # @return [String] The base URL
+      def self.get_base_url(local_port)
+        local_port ? "http://localhost:#{local_port}/api/v1" : BASE_URL
+      end
+
+      # Returns the currently active API key.
+      #
+      # @return [String] The current API key
+      def api_key
+        @current_api_key
+      end
+
+      # Returns the key identifier for the current API key.
+      #
+      # @return [String] The key ID (first 8 characters)
+      def key_id
+        Utils::Security.get_key_id(@current_api_key)
+      end
+
+      # Checks if key rotation is currently active.
+      #
+      # @return [Boolean] true if within the key rotation grace period
+      def in_key_rotation?
+        return false unless @key_rotation_timestamp
+
+        elapsed = Time.now - @key_rotation_timestamp
+        elapsed < @key_rotation_grace_period
+      end
+
+      # @param api_key [String] The API key
+      # @param timeout [Integer] Request timeout in seconds
+      # @param retry_attempts [Integer] Number of retry attempts
+      # @param circuit_breaker [CircuitBreaker] The circuit breaker
+      # @param logger [Object, nil] Logger instance
+      # @param local_port [Integer, nil] Local development server port
+      # @param secondary_api_key [String, nil] Secondary API key for rotation
+      # @param key_rotation_grace_period [Integer] Grace period in seconds
+      # @param enable_request_signing [Boolean] Enable HMAC-SHA256 request signing
+      # @param on_usage_update [Proc, nil] Callback for usage metrics updates
+      def initialize(
+        api_key:,
+        timeout:,
+        retry_attempts:,
+        circuit_breaker:,
+        logger: nil,
+        local_port: nil,
+        secondary_api_key: nil,
+        key_rotation_grace_period: 300,
+        enable_request_signing: true,
+        on_usage_update: nil
+      )
+        @base_url = self.class.get_base_url(local_port)
+        @primary_api_key = api_key
+        @secondary_api_key = secondary_api_key
+        @current_api_key = api_key
+        @key_rotation_grace_period = key_rotation_grace_period
+        @key_rotation_timestamp = nil
+        @enable_request_signing = enable_request_signing
+        @timeout = timeout
+        @retry_attempts = retry_attempts
+        @circuit_breaker = circuit_breaker
+        @logger = logger
+        @on_usage_update = on_usage_update
+        @connection = build_connection
+      end
+
+      # Makes a GET request.
+      #
+      # @param path [String] The request path
+      # @param params [Hash] Query parameters
+      # @return [Hash] The response body
+      def get(path, params = {})
+        request(:get, path, params: params)
+      end
+
+      # Makes a POST request with automatic request signing.
+      #
+      # @param path [String] The request path
+      # @param body [Hash] The request body
+      # @return [Hash] The response body
+      def post(path, body = {})
+        signing_headers = {}
+
+        if @enable_request_signing && !body.empty?
+          body_string = body.to_json
+          sig_data = Utils::Security.create_request_signature(body_string, @current_api_key)
+          signing_headers["X-Signature"] = sig_data[:signature]
+          signing_headers["X-Timestamp"] = sig_data[:timestamp].to_s
+          signing_headers["X-Key-Id"] = sig_data[:key_id]
+        end
+
+        request(:post, path, body: body, extra_headers: signing_headers)
+      end
+
+      private
+
+      # Rotates to the secondary API key on authentication failure.
+      #
+      # @return [Boolean] true if rotation was performed
+      def rotate_to_secondary_key
+        return false unless @secondary_api_key
+        return false if @current_api_key == @secondary_api_key
+
+        log(:info, "Rotating to secondary API key due to authentication failure")
+        @current_api_key = @secondary_api_key
+        @key_rotation_timestamp = Time.now
+        rebuild_connection
+        true
+      end
+
+      def rebuild_connection
+        @connection = build_connection
+      end
+
+      def build_connection
+        Faraday.new(url: @base_url) do |conn|
+          conn.options.timeout = timeout
+          conn.options.open_timeout = timeout
+          conn.headers["Content-Type"] = "application/json"
+          conn.headers["Accept"] = "application/json"
+          conn.headers["X-API-Key"] = @current_api_key
+          conn.headers["User-Agent"] = "FlagKit-Ruby/#{VERSION}"
+          conn.headers["X-FlagKit-SDK-Version"] = VERSION
+          conn.headers["X-FlagKit-SDK-Language"] = "ruby"
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def request(method, path, params: nil, body: nil, extra_headers: {})
+        unless circuit_breaker.allow_request?
+          raise FlagKit::Error.new(ErrorCode::CIRCUIT_OPEN, "Circuit breaker is open")
+        end
+
+        attempts = 0
+        last_error = nil
+
+        loop do
+          attempts += 1
+          begin
+            response = execute_request(method, path, params, body, extra_headers)
+            circuit_breaker.record_success
+            return parse_response(response)
+          rescue Faraday::TimeoutError => e
+            last_error = FlagKit::Error.network_error("Request timed out", cause: e)
+          rescue Faraday::ConnectionFailed => e
+            last_error = FlagKit::Error.network_error("Connection failed: #{e.message}", cause: e)
+          rescue FlagKit::Error => e
+            last_error = e
+
+            # Handle 401 errors with key rotation
+            if e.code == ErrorCode::AUTH_INVALID_KEY && @secondary_api_key
+              if rotate_to_secondary_key
+                log(:debug, "Retrying request with secondary API key")
+                attempts -= 1 # Don't count rotation retry against attempt limit
+                next
+              end
+            end
+
+            # Don't retry on non-recoverable errors
+            raise e unless e.recoverable?
+          rescue StandardError => e
+            last_error = FlagKit::Error.network_error("Request failed: #{e.message}", cause: e)
+          end
+
+          if attempts >= retry_attempts
+            circuit_breaker.record_failure
+            raise last_error
+          end
+
+          sleep(calculate_backoff(attempts))
+        end
+      end
+
+      def execute_request(method, path, params, body, extra_headers = {})
+        @connection.run_request(method, path, body&.to_json, nil) do |req|
+          req.params.update(params) if params
+          extra_headers.each { |k, v| req.headers[k] = v }
+        end
+      end
+
+      def parse_response(response)
+        # Extract and process usage metrics from headers
+        usage_metrics = extract_usage_metrics(response.headers)
+        if usage_metrics && @on_usage_update
+          @on_usage_update.call(usage_metrics)
+        end
+
+        case response.status
+        when 200..299
+          return {} if response.body.nil? || response.body.empty?
+
+          JSON.parse(response.body)
+        when 401
+          raise FlagKit::Error.auth_error(ErrorCode::AUTH_INVALID_KEY, "Invalid API key")
+        when 403
+          raise FlagKit::Error.auth_error(ErrorCode::AUTH_PERMISSION_DENIED, "Permission denied")
+        when 404
+          raise FlagKit::Error.new(ErrorCode::EVAL_FLAG_NOT_FOUND, "Resource not found")
+        when 429
+          raise FlagKit::Error.new(ErrorCode::NETWORK_RETRY_LIMIT, "Rate limit exceeded")
+        when 500..599
+          raise FlagKit::Error.network_error("Server error: #{response.status}")
+        else
+          raise FlagKit::Error.network_error("Unexpected response status: #{response.status}")
+        end
+      end
+
+      # Extracts usage metrics from response headers.
+      #
+      # @param headers [Hash] Response headers
+      # @return [UsageMetrics, nil] Usage metrics if any usage headers present
+      def extract_usage_metrics(headers)
+        api_usage = headers["x-api-usage-percent"]
+        eval_usage = headers["x-evaluation-usage-percent"]
+        rate_limit_warning = headers["x-rate-limit-warning"]
+        subscription_status = headers["x-subscription-status"]
+
+        # Return nil if no usage headers present
+        return nil unless api_usage || eval_usage || rate_limit_warning || subscription_status
+
+        api_usage_percent = api_usage ? (Float(api_usage) rescue nil) : nil
+        evaluation_usage_percent = eval_usage ? (Float(eval_usage) rescue nil) : nil
+        warning_flag = rate_limit_warning == "true"
+
+        # Log warnings for high usage
+        if api_usage_percent && api_usage_percent >= 80
+          log(:warn, "API usage at #{api_usage_percent}%")
+        end
+        if evaluation_usage_percent && evaluation_usage_percent >= 80
+          log(:warn, "Evaluation usage at #{evaluation_usage_percent}%")
+        end
+        if subscription_status == "suspended"
+          log(:error, "Subscription suspended - service degraded")
+        end
+
+        UsageMetrics.new(
+          api_usage_percent: api_usage_percent,
+          evaluation_usage_percent: evaluation_usage_percent,
+          rate_limit_warning: warning_flag,
+          subscription_status: subscription_status
+        )
+      end
+
+      def calculate_backoff(attempt)
+        delay = BASE_RETRY_DELAY * (RETRY_MULTIPLIER**(attempt - 1))
+        delay = [delay, MAX_RETRY_DELAY].min
+        jitter = delay * JITTER_FACTOR * rand
+        delay + jitter
+      end
+
+      def log(level, message)
+        return unless @logger
+
+        @logger.send(level, "[FlagKit::HttpClient] #{message}")
+      end
+    end
+  end
+
+  # Alias for backward compatibility
+  HttpClient = Http::HttpClient
+end