ibm_appconfiguration_ruby_sdk 0.1.0.pre.rc.0

data/lib/ibm_appconfiguration_ruby_sdk/configurations/internal/constants.rb

@@ -0,0 +1,89 @@
+# Copyright 2026 IBM Corp. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# frozen_string_literal: true
+
+##
+# This file defines the various constants used by the SDK.
+#
+module Constants
+  # Maximum number of retries for API requests
+  MAX_NUMBER_OF_RETRIES = 3
+
+  # HTTP Status codes
+  STATUS_CODE_OK = 200
+  STATUS_CODE_ACCEPTED = 202
+
+  # Socket constants
+  CUSTOM_SOCKET_CLOSE_REASON_CODE = 4001
+  SOCKET_CONNECTION_ERROR = "Socket connection error"
+  SOCKET_LOST_ERROR = "Socket connection lost"
+  SOCKET_CONNECTION_CLOSE = "Socket connection is closed"
+  SOCKET_INCOMING_DATA = "Received data from socket"
+  SOCKET_MESSAGE_RECEIVED = "Message received from server"
+  SOCKET_CALLBACK = "Message passed to handler"
+  SOCKET_MESSAGE_ERROR = "Message received from server is invalid"
+  SOCKET_CONNECTION_SUCCESS = "Successfully connected to App Configuration server"
+  APPCONFIGURATION_CLIENT_EMITTER = "configurationUpdate"
+
+  # Error messages
+  REGION_ERROR = "Provide a valid region in App Configuration init"
+  GUID_ERROR = "Provide a valid guid in App Configuration init"
+  APIKEY_ERROR = "Provide a valid apiKey in App Configuration init"
+  COLLECTION_ID_VALUE_ERROR = "Provide a valid collectionId in App Configuration setContext method."
+  ENVIRONMENT_ID_VALUE_ERROR = "Provide a valid environmentId in App Configuration setContext method."
+  COLLECTION_ID_ERROR = "Invalid action in App Configuration. This action can be performed only after a successful initialization."
+  COLLECTION_INIT_ERROR = "Invalid action in App Configuration. This action can be performed only after a successful initialization and setting the context."
+  INVALID_OPTIONS_PARAMTER = "options param passed to setContext is invalid. Should be a Hash"
+  CONFIGURATION_FILE_NOT_FOUND_ERROR = "bootstrapFile parameter should be provided while liveConfigUpdateEnabled is false during initialization."
+  PERSISTENT_CACHE_OPTION_ERROR = "setContext: [options.persistentCacheDirectory]. Invalid value -"
+  BOOTSTRAP_FILEPATH_OPTION_ERROR = "setContext: [options.bootstrapFile]. Invalid value -"
+  LIVE_CONFIG_UPDATE_OPTION_ERROR = "setContext: [options.liveConfigUpdateEnabled]. Invalid value -"
+  BOOTSTRAP_FILEPATH_NOT_FOUND_ERROR = "setContext: [options.bootstrapFile] parameter should be provided when [options.liveConfigUpdateEnabled] is false."
+  NO_INTERNET_CONNECTION_ERROR = "Check for network connectivity failed. Re-checking..."
+  INVALID_ENTITY_ID = "Invalid entityId passed to"
+  SINGLETON_EXCEPTION = "Initialize object first"
+
+  # Default values
+  DEFAULT_SEGMENT_ID = "$$null$$"
+  DEFAULT_ENTITY_ID = "$$null$$"
+  DEFAULT_USAGE_LIMIT = 10
+  DEFAULT_ROLLOUT_PERCENTAGE = "$default"
+  DEFAULT_FEATURE_VALUE = "$default"
+  DEFAULT_PROPERTY_VALUE = "$default"
+
+  # Secret Manager
+  INVALID_SECRET_MANAGER_CLIENT_MESSAGE = "Secret Manager object passed to getSecret method is null or undefined."
+  SECRETREF = "SECRETREF"
+
+  # Success messages
+  SUCCESSFULLY_FETCHED_THE_CONFIGURATIONS = "Successfully fetched the configurations"
+  SUCCESSFULLY_POSTED_METERING_DATA = "Successfully posted metering data"
+  SUCCESSFULLY_POSTED_EXPERIMENT_EVALUATION_EVENTS = "Successfully posted evaluation events"
+  SUCCESSFULLY_POSTED_EXPERIMENT_METRIC_EVENTS = "Successfully posted metric events"
+
+  # Error messages for posting data
+  ERROR_POSTING_METERING_DATA = "Error while posting metering data"
+  ERROR_POSTING_EXPERIMENT_EVALUATION_EVENTS = "Error while posting evaluation events"
+  ERROR_POSTING_EXPERIMENT_METRIC_EVENTS = "Error while posting metric events"
+  ERROR_NO_WRITE_PERMISSION = "Persistent cache directory provided doesn't have write permission. Make sure the directory has required access."
+  INPUT_PARAMETER_NOT_BOOLEAN = "Input parameter passed to usePrivateEndpoint() method is not boolean. Default value will be used."
+
+  # Rollout types
+  MANUAL = "MANUAL"
+  PROGRESSIVE = "PROGRESSIVE"
+
+  # Delimiter
+  DELIMITER = "\u001F"
+end

data/lib/ibm_appconfiguration_ruby_sdk/configurations/internal/file_manager.rb

@@ -0,0 +1,72 @@
+# Copyright 2026 IBM Corp. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# frozen_string_literal: true
+
+require "singleton"
+require_relative "logger"
+
+# This module provides methods that perform the store and retrieve operations on the
+# file based cache of the SDK.
+class FileManager
+  include Singleton
+
+  def initialize
+    @logger = Logger.instance
+  end
+
+  def store_files(json, file_path)
+    File.write(file_path, json)
+  end
+
+  def read_persistent_cache_configurations(file_path)
+    unless File.exist?(file_path)
+      @logger.log("configuration file in the persistent cache doesn't exist")
+      return ""
+    end
+
+    data = File.read(file_path).strip
+
+    if data.empty?
+      @logger.log("configuration file in the persistent cache is empty")
+      return ""
+    end
+
+    data
+  rescue StandardError
+    ""
+  end
+
+  def read_bootstrap_configurations_from_file(file_path)
+    raise "given bootstrap file path doesn't exist: #{file_path}" unless File.exist?(file_path)
+
+    data = File.read(file_path).strip
+
+    raise "given bootstrap file is empty: #{file_path}" if data.empty?
+
+    begin
+      data
+    rescue StandardError => e
+      raise "failed to parse the json from the given bootstrap file: #{file_path}. Error #{e}"
+    end
+  end
+
+  def delete_file_data(file_path)
+    return unless File.exist?(file_path)
+
+    File.truncate(file_path, 0)
+  rescue StandardError => e
+    @logger.warning(e)
+  end
+end

data/lib/ibm_appconfiguration_ruby_sdk/configurations/internal/logger.rb

@@ -0,0 +1,98 @@
+# Copyright 2026 IBM Corp. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# frozen_string_literal: true
+
+# Logger class for SDK logging with color-coded output
+require "singleton"
+
+class Logger
+  include Singleton
+
+  @debug = false
+
+  class << self
+    # Enable or disable debug logging
+    # @param value [Boolean] true to enable debug logging, false to disable
+    def set_debug(value = false)
+      @debug = value
+    end
+
+    # Check if debug logging is enabled
+    # @return [Boolean] true if debug is enabled, false otherwise
+    def debug?
+      @debug
+    end
+  end
+
+  # Generate timestamp for log messages
+  # @return [String] formatted timestamp
+  def timestamp
+    "#{Time.now.strftime("%Y-%m-%d %H:%M:%S")} AppConfiguration"
+  end
+
+  # Log debug message (only if debug is enabled)
+  # @param message [String] the message to log
+  def log(message)
+    return unless self.class.debug?
+
+    puts "#{timestamp} DEBUG #{message}"
+  end
+
+  # Log error message (always shown)
+  # @param message [String] the error message to log
+  def error(message)
+    puts "#{timestamp} ERROR #{colorize(message, :red)}"
+  end
+
+  # Log warning message (only if debug is enabled)
+  # @param message [String] the warning message to log
+  def warning(message)
+    return unless self.class.debug?
+
+    puts "#{timestamp} WARNING #{colorize(message, :yellow)}"
+  end
+
+  # Log success message (only if debug is enabled)
+  # @param message [String] the success message to log
+  def success(message)
+    return unless self.class.debug?
+
+    puts "#{timestamp} SUCCESS #{colorize(message, :green)}"
+  end
+
+  # Log info message (always shown)
+  # @param message [String] the info message to log
+  def info(message)
+    puts "#{timestamp} INFO #{colorize(message, :blue)}"
+  end
+
+  private
+
+  # Colorize text for terminal output
+  # @param text [String] the text to colorize
+  # @param color [Symbol] the color to apply (:red, :green, :yellow, :blue)
+  # @return [String] colorized text
+  def colorize(text, color)
+    color_codes = {
+      red: "\e[1;31m",
+      green: "\e[1;32m",
+      yellow: "\e[1;33m",
+      blue: "\e[1;44m",
+      reset: "\e[0m"
+    }
+
+    "#{color_codes[color]}#{text}#{color_codes[:reset]}"
+  end
+end

data/lib/ibm_appconfiguration_ruby_sdk/configurations/internal/retry_manager/background_retry_manager.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+# Copyright 2026 IBM Corp. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative "config_fetcher"
+require_relative "../logger"
+
+# BackgroundRetryManager
+#
+# Implements exponential backoff retry strategy for long-term configuration fetch failures.
+# This is the "Tier 2" retry mechanism that activates after immediate retries fail.
+#
+# Key Features:
+# - Exponential backoff: Delays increase exponentially (2^attempt)
+# - Jitter: Random delays prevent thundering herd
+# - Cap: Maximum delay capped at ~1 hour
+# - Thread-safe: Uses Mutex for concurrent access
+# - Graceful shutdown: Properly cleans up threads
+#
+# Retry Timeline Example:
+#   Attempt 1: ~2.3 minutes
+#   Attempt 2: ~4.7 minutes
+#   Attempt 3: ~9.1 minutes
+#   Attempt 4: ~18.5 minutes
+#   Attempt 5: ~37.2 minutes
+#   Attempt 6+: ~60 minutes (capped)
+#
+class BackgroundRetryManager
+  attr_reader :active, :attempt
+
+  # Initialize the retry manager
+  #
+  # @param collection_id [String] Collection ID for API request
+  # @param environment_id [String] Environment ID for API request
+  # @param logger [Logger] Optional logger instance (creates new one if not provided)
+  def initialize(collection_id:, environment_id:, logger: nil)
+    @collection_id = collection_id
+    @environment_id = environment_id
+    @logger = logger || Logger.instance
+
+    # Initialize ConfigFetcher
+    @config_fetcher = ConfigFetcher.new(
+      collection_id: collection_id,
+      environment_id: environment_id,
+      logger: @logger
+    )
+
+    # State management
+    @active = false
+    @attempt = 0
+    @cap_ms = nil
+
+    # Thread management
+    @retry_thread = nil
+    @mutex = Mutex.new
+
+    @logger.info("BackgroundRetryManager initialized")
+  end
+
+  # Start the background retry loop
+  #
+  # This method:
+  # 1. Checks if retry is already active (prevents duplicate retries)
+  # 2. Initializes retry state (attempt counter, cap delay)
+  # 3. Schedules the first retry attempt
+  #
+  # @param reason [String] The reason for starting retry (for logging)
+  # @return [Boolean] true if started, false if already active
+  def start(reason:)
+    # Thread-safe check and initialization
+    should_start = false
+
+    @mutex.synchronize do
+      if @active
+        @logger.info("⚠️  Background retry already active (attempt ##{@attempt}). Reason: #{reason}")
+        return false
+      end
+
+      # Initialize retry state
+      @active = true
+      @attempt = 0
+      @cap_ms = compute_cap_delay_ms
+      should_start = true
+    end
+
+    if should_start
+      cap_hours = (@cap_ms / 3_600_000.0).round(2)
+      @logger.info("🔄 Starting background retry (cap #{cap_hours} hours). Reason: #{reason}")
+      schedule_next_attempt(reason)
+    end
+
+    true
+  end
+
+  # Stop the background retry loop
+  #
+  # This method:
+  # 1. Sets active flag to false (stops scheduling new attempts)
+  # 2. Kills the current retry thread if running
+  # 3. Resets all state variables
+  #
+  # Thread-safe and idempotent (safe to call multiple times)
+  def stop
+    @mutex.synchronize do
+      return unless @active
+
+      @active = false
+      @attempt = 0
+      @cap_ms = nil
+    end
+
+    # Kill retry thread outside mutex to avoid deadlock
+    if @retry_thread&.alive?
+      @retry_thread.kill
+      @retry_thread = nil
+    end
+
+    @logger.info("✓ Background retry stopped")
+  end
+
+  # Check if retry is currently active
+  #
+  # @return [Boolean] true if retry loop is running
+  def active?
+    @mutex.synchronize { @active }
+  end
+
+  # Get current attempt number
+  #
+  # @return [Integer] Current retry attempt (0-based)
+  def current_attempt
+    @mutex.synchronize { @attempt }
+  end
+
+  private
+
+  # Schedule the next retry attempt
+  #
+  # This is the core of the retry mechanism:
+  # 1. Calculates delay using exponential backoff (0 for first attempt)
+  # 2. Logs the schedule
+  # 3. Spawns a thread that:
+  #    - Sleeps for the calculated delay (0 for first attempt)
+  #    - Executes the retry (calls fetch_from_api)
+  #    - Decides next action based on result
+  #
+  # @param reason [String] Reason for this retry attempt
+  def schedule_next_attempt(reason)
+    # First attempt (attempt 0) happens immediately, subsequent attempts use exponential backoff
+    delay_ms = @attempt.zero? ? 0 : compute_next_delay_ms(@attempt, @cap_ms)
+    delay_sec = delay_ms / 1000.0
+    delay_min = (delay_ms / 60_000.0).round(2)
+
+    if @attempt.zero?
+      @logger.warning("⏰ #{reason} - Starting first retry attempt immediately")
+    else
+      @logger.warning("⏰ #{reason} - Retry scheduled in #{delay_min} minutes (attempt ##{@attempt + 1})")
+    end
+
+    # Spawn new thread for this retry attempt
+    @retry_thread = Thread.new do
+      # Sleep for the calculated delay
+      # First attempt: 0 seconds (immediate)
+      # Subsequent attempts: exponential backoff
+      sleep(delay_sec)
+
+      # Check if still active after sleep (might have been stopped)
+      next unless @active
+
+      @logger.info("🔄 Executing retry attempt ##{@attempt + 1}")
+
+      # Execute the retry by calling ConfigFetcher
+      result = @config_fetcher.fetch
+
+      # Decision tree based on result
+      if result[:ok]
+        # ✅ SUCCESS: Configuration fetched successfully
+        @logger.info("=" * 80)
+        @logger.info("✅ SUCCESS: Configurations fetched successfully!")
+        @logger.info("=" * 80)
+        @config_fetcher.display_response(result[:data])
+        @config_fetcher.process_and_load_configurations(result[:data])
+        stop
+        next
+      end
+
+      unless result[:retryable]
+        # ❌ NON-RETRYABLE ERROR: Client error (4xx except 429)
+        # Stop retrying - user needs to fix the issue
+        @logger.error("❌ Non-retryable error (#{result[:status]}) - stopping retry")
+        stop
+        next
+      end
+
+      # 🔄 RETRYABLE ERROR: 429 or 5xx
+      # Increment attempt counter and schedule next retry
+      @mutex.synchronize do
+        @attempt += 1
+      end
+
+      next_reason = "Failed to fetch configurations. Status: #{result[:status]}"
+      @logger.warning("⚠️  Retry attempt ##{@attempt} failed - scheduling next attempt")
+
+      # Recursive call to schedule next attempt with increased delay
+      schedule_next_attempt(next_reason)
+    rescue StandardError => e
+      # Handle any unexpected errors in the retry thread
+      @logger.error("❌ Error in retry thread: #{e.message}")
+      @logger.error(e.backtrace.join("\n"))
+
+      # Try to schedule next attempt if still active
+      if @active
+        @mutex.synchronize { @attempt += 1 }
+        schedule_next_attempt("Exception in retry: #{e.message}")
+      end
+    end
+  end
+
+  # Compute base delay with jitter
+  #
+  # Base delay: 2 minutes (120,000 ms)
+  # Jitter: 0-54 seconds (0-54,000 ms)
+  # Total: 2.0 - 2.9 minutes
+  #
+  # Jitter prevents synchronized retries across multiple clients
+  # (thundering herd problem)
+  #
+  # @return [Integer] Base delay in milliseconds
+  def compute_base_delay_ms
+    base_ms = 2 * 60 * 1000 # 2 minutes = 120,000 ms
+    jitter_ms = (0.9 * 60 * 1000 * rand).floor # 0-54 seconds
+    base_ms + jitter_ms
+  end
+
+  # Compute cap delay with jitter
+  #
+  # Cap: 1 hour (3,600,000 ms)
+  # Jitter: 0-59 seconds (0-59,000 ms)
+  # Total: 60:00 - 60:59 minutes
+  #
+  # This is the maximum delay between retries
+  #
+  # @return [Integer] Cap delay in milliseconds
+  def compute_cap_delay_ms
+    base_ms = 60 * 60 * 1000 # 1 hour = 3,600,000 ms
+    jitter_seconds = rand(60) # 0-59 seconds
+    base_ms + (jitter_seconds * 1000)
+  end
+
+  # Compute next delay using exponential backoff
+  #
+  # Formula: min(base_delay * 2^attempt, cap_delay)
+  #
+  # Example progression:
+  #   Attempt 0: 2.3 min * 2^0 = 2.3 min
+  #   Attempt 1: 2.3 min * 2^1 = 4.6 min
+  #   Attempt 2: 2.3 min * 2^2 = 9.2 min
+  #   Attempt 3: 2.3 min * 2^3 = 18.4 min
+  #   Attempt 4: 2.3 min * 2^4 = 36.8 min
+  #   Attempt 5: 2.3 min * 2^5 = 73.6 min → capped at 60 min
+  #
+  # @param attempt [Integer] Current attempt number (0-based)
+  # @param cap_ms [Integer] Maximum delay in milliseconds
+  # @return [Integer] Calculated delay in milliseconds
+  def compute_next_delay_ms(attempt, cap_ms)
+    # Calculate exponential delay
+    exp_ms = compute_base_delay_ms * (2**attempt)
+
+    # Cap at maximum delay
+    [exp_ms, cap_ms].min
+  end
+end