unleash 6.4.0 → 6.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a76eb26bedcade3ed88389aa909f7ead99177e336509bc4fd99d85c4703f1405
-  data.tar.gz: 43410bf468ac4fd3b56af79a354eb84794c40c67b6c2d96c27bdf26772b1c54d
+  metadata.gz: 8f2aacf28333e06f4ca46369b9ece6fd1472a8e363cdc4a0fe1aeb0810d879a2
+  data.tar.gz: bc8e366ec18bff858f835260af79650ab6179daa6af93bf84a675eb3d74ad904
 SHA512:
-  metadata.gz: 3e43cbef4ba85e84265f10b9414eba95c92aeb59792a40318e15df37313ee5a6b99ce3c3e3e89d465c56e40fff92e61ed4115766d59b6ee9147c2d2c5920ebf7
-  data.tar.gz: 2401fa3bf2d0f824d7da3cf2e01cc4c20fe740f26d2019f89554adbbc67fdc5c0f4fa65003e143391b14ea2466314db36852edd0ccefca8178f6545e3186170d
+  metadata.gz: 9c397ef806b4e77fb8a1d8afbacd3ded420f5979fcf1999b03e524d77dca3f04205fa28e4a1e83037c7670837654c5f0e193f74b53654dedb034c1e9016fb22e
+  data.tar.gz: 07bfa665ecb17ffbe86b9dbb66c3247d824a27e27d846000f181ad5783d8af3a6e9adb9a47d2e2f37732bec80c137683609b63726cd58616164efe464a4fcd4c

data/CHANGELOG.md

@@ -13,6 +13,16 @@ Note: These changes are not considered notable:
 
 ## [Unreleased]
 
+## [6.5.0] - 2026-01-29
+
+### Added
+- Impact metrics 
+
+## [6.4.1] - 2025-12-04
+
+### Changed
+- Bump yggdrasil-engine
+
 ## [6.4.0] - 2025-08-12
 ### Added
 - Experimental streaming support

data/README.md

@@ -28,7 +28,7 @@ You can use this client with [Unleash Enterprise](https://www.getunleash.io/pric
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'unleash', '~> 6.3.0'
+gem 'unleash', '~> 6.5.0'
 ```
 
 And then execute:
@@ -534,6 +534,56 @@ Unleash.configure do |config|
 end
 ```
 
+## Impact metrics
+
+Impact metrics are lightweight, application-level time-series metrics stored and visualized directly inside Unleash. They allow you to connect specific application data, such as request counts, error rates, or latency, to your feature flags and release plans.
+
+These metrics help validate feature impact and automate release processes. For instance, you can monitor usage patterns or performance to determine if a feature meets its goals.
+
+The SDK automatically attaches context labels to metrics: `appName` and `environment`.
+
+### Counters
+
+Use counters for cumulative values that only increase (total requests, errors):
+
+```ruby
+client = Unleash::Client.new
+
+client.impact_metrics.define_counter(
+  'request_count',
+  'Total number of HTTP requests processed'
+)
+
+client.impact_metrics.increment_counter('request_count')
+```
+
+### Gauges
+
+Use gauges for point-in-time values that can go up or down:
+
+```ruby
+client.impact_metrics.define_gauge(
+  'total_users',
+  'Total number of registered users'
+)
+
+client.impact_metrics.update_gauge('total_users', user_count)
+```
+
+### Histograms
+
+Histograms measure value distribution (request duration, response size):
+
+```ruby
+client.impact_metrics.define_histogram(
+  'request_time_ms',
+  'Time taken to process a request in milliseconds',
+  [50, 100, 200, 500, 1000]
+)
+
+client.impact_metrics.observe_histogram('request_time_ms', 125)
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.

data/lib/unleash/backup_file_reader.rb

@@ -0,0 +1,24 @@
+require 'unleash/configuration'
+
+module Unleash
+  class BackupFileReader
+    def self.read!
+      Unleash.logger.debug "read!()"
+
+      backup_file = Unleash.configuration.backup_file
+      return nil unless File.exist?(backup_file)
+
+      File.read(backup_file)
+    rescue IOError => e
+      # :nocov:
+      Unleash.logger.error "Unable to read the backup_file: #{e}"
+      # :nocov:
+      nil
+    rescue StandardError => e
+      # :nocov:
+      Unleash.logger.error "Unable to extract valid data from backup_file. Exception thrown: #{e}"
+      # :nocov:
+      nil
+    end
+  end
+end

data/lib/unleash/backup_file_writer.rb

@@ -0,0 +1,21 @@
+require 'unleash/configuration'
+
+module Unleash
+  class BackupFileWriter
+    def self.save!(toggle_data)
+      Unleash.logger.debug "Will save toggles to disk now"
+
+      backup_file = Unleash.configuration.backup_file
+      backup_file_tmp = "#{backup_file}.tmp-#{Process.pid}"
+
+      File.open(backup_file_tmp, "w") do |file|
+        file.write(toggle_data)
+      end
+      File.rename(backup_file_tmp, backup_file)
+    rescue StandardError => e
+      # This is not really the end of the world. Swallowing the exception.
+      Unleash.logger.error "Unable to save backup file. Exception thrown #{e.class}:'#{e}'"
+      Unleash.logger.error "stacktrace: #{e.backtrace}"
+    end
+  end
+end

data/lib/unleash/client.rb

@@ -6,12 +6,15 @@ require 'unleash/streaming_client_executor'
 require 'unleash/variant'
 require 'unleash/util/http'
 require 'unleash/util/event_source_wrapper'
+require 'unleash/environment_resolver'
+require 'unleash/impact_metrics'
 require 'logger'
 require 'time'
 
 module Unleash
   class Client
     attr_accessor :fetcher_scheduled_executor, :metrics_scheduled_executor
+    attr_reader :impact_metrics
 
     # rubocop:disable Metrics/AbcSize
     def initialize(*opts)
@@ -23,6 +26,8 @@ module Unleash
       Unleash.engine = YggdrasilEngine.new
       Unleash.engine.register_custom_strategies(Unleash.configuration.strategies.custom_strategies)
 
+      @impact_metrics = ImpactMetrics.new(Unleash.engine, Unleash.configuration.app_name)
+
       Unleash.toggle_fetcher = Unleash::ToggleFetcher.new Unleash.engine unless Unleash.configuration.streaming_mode?
 
       if Unleash.configuration.disable_client

data/lib/unleash/configuration.rb

@@ -107,6 +107,12 @@ module Unleash
         self.experimental_mode[:format] == 'delta'
     end
 
+    def generate_custom_http_headers
+      return self.custom_http_headers.call if self.custom_http_headers.respond_to?(:call)
+
+      self.custom_http_headers
+    end
+
     private
 
     def set_defaults
@@ -153,12 +159,6 @@ module Unleash
       raise ArgumentError, "custom_http_headers must be a Hash or a Proc."
     end
 
-    def generate_custom_http_headers
-      return self.custom_http_headers.call if self.custom_http_headers.respond_to?(:call)
-
-      self.custom_http_headers
-    end
-
     def set_option(opt, val)
       __send__("#{opt}=", val)
     rescue NoMethodError

data/lib/unleash/environment_resolver.rb

@@ -0,0 +1,27 @@
+module Unleash
+  class EnvironmentResolver
+    def self.extract_environment_from_custom_headers(custom_headers)
+      authorization_header = extract_authorization_header(custom_headers)
+      extract_environment_from_header(authorization_header)
+    end
+
+    def self.extract_authorization_header(custom_headers)
+      return nil if custom_headers.nil? || !custom_headers.is_a?(Hash)
+
+      key = custom_headers.keys.find{ |k| k.to_s.downcase == 'authorization' }
+      custom_headers[key] if key
+    end
+
+    def self.extract_environment_from_header(authorization_header)
+      return nil if authorization_header.nil? || authorization_header.empty?
+
+      after_colon = authorization_header.split(':', 2)[1]
+      return nil unless after_colon&.include?('.')
+
+      environment = after_colon.split('.')[0]
+      environment unless environment.empty?
+    end
+
+    private_class_method :extract_authorization_header, :extract_environment_from_header
+  end
+end

data/lib/unleash/impact_metrics.rb

@@ -0,0 +1,43 @@
+module Unleash
+  class ImpactMetrics
+    def initialize(engine, app_name)
+      @engine = engine
+      @app_name = app_name
+    end
+
+    def define_counter(name, help_text)
+      @engine.define_counter(name, help_text)
+    end
+
+    def increment_counter(name, value = 1)
+      @engine.inc_counter(name, value, base_labels)
+    end
+
+    def define_gauge(name, help_text)
+      @engine.define_gauge(name, help_text)
+    end
+
+    def update_gauge(name, value)
+      @engine.set_gauge(name, value, base_labels)
+    end
+
+    def define_histogram(name, help_text, buckets = nil)
+      @engine.define_histogram(name, help_text, buckets)
+    end
+
+    def observe_histogram(name, value)
+      @engine.observe_histogram(name, value, base_labels)
+    end
+
+    private
+
+    def base_labels
+      {
+        'appName' => @app_name,
+        'environment' => EnvironmentResolver.extract_environment_from_custom_headers(
+          Unleash.configuration.generate_custom_http_headers
+        ) || Unleash.configuration.environment
+      }
+    end
+  end
+end

data/lib/unleash/metrics_reporter.rb

@@ -23,7 +23,8 @@ module Unleash
     def post
       Unleash.logger.debug "post() Report"
 
-      report = build_report
+      impact_metrics = collect_impact_metrics_safely
+      report = build_report(impact_metrics)
       return unless report
 
       send_report(report)
@@ -44,15 +45,20 @@ module Unleash
       }
     end
 
-    def build_report
+    def build_report(impact_metrics)
       report = generate_report
-      return nil if report.nil? && Time.now - self.last_time < LONGEST_WITHOUT_A_REPORT
+      has_data = !report.nil? || !impact_metrics.empty?
 
-      report || generate_report_from_bucket({
+      return nil if !has_data && Time.now - self.last_time < LONGEST_WITHOUT_A_REPORT
+
+      report ||= generate_report_from_bucket({
         'start': self.last_time.utc.iso8601,
         'stop': Time.now.utc.iso8601,
         'toggles': {}
       })
+
+      report[:impactMetrics] = impact_metrics unless impact_metrics.empty?
+      report
     end
 
     def send_report(report)
@@ -66,8 +72,24 @@ module Unleash
       else
         # :nocov:
         Unleash.logger.error "Error when sending report to unleash server. Server responded with http code #{response.code}."
+        restore_impact_metrics(report[:impactMetrics])
         # :nocov:
       end
     end
+
+    def restore_impact_metrics(impact_metrics)
+      return if impact_metrics.nil? || impact_metrics.empty?
+
+      Unleash.engine&.restore_impact_metrics(impact_metrics)
+    rescue StandardError => e
+      Unleash.logger.warn "Failed to restore impact metrics: #{e.message}"
+    end
+
+    def collect_impact_metrics_safely
+      Unleash.engine&.collect_impact_metrics || []
+    rescue StandardError => e
+      Unleash.logger.warn "Failed to collect impact metrics: #{e.message}"
+      []
+    end
   end
 end

data/lib/unleash/spec_version.rb

@@ -1,3 +1,3 @@
 module Unleash
-  CLIENT_SPECIFICATION_VERSION = "5.2.0".freeze
+  CLIENT_SPECIFICATION_VERSION = "5.2.2".freeze
 end

data/lib/unleash/streaming_client_executor.rb

@@ -1,4 +1,6 @@
 require 'unleash/streaming_event_processor'
+require 'unleash/bootstrap/handler'
+require 'unleash/backup_file_reader'
 require 'unleash/util/event_source_wrapper'
 
 module Unleash
@@ -10,6 +12,20 @@ module Unleash
       self.event_source = nil
       self.event_processor = Unleash::StreamingEventProcessor.new(engine)
       self.running = false
+
+      begin
+        # if bootstrap configuration is available, initialize. Otherwise read backup file
+        if Unleash.configuration.use_bootstrap?
+          bootstrap(engine)
+        else
+          read_backup_file!(engine)
+        end
+      rescue StandardError => e
+        # fall back to reading the backup file
+        Unleash.logger.warn "StreamingClientExecutor was unable to initialize, attempting to read from backup file."
+        Unleash.logger.debug "Exception Caught: #{e}"
+        read_backup_file!(engine)
+      end
     end
 
     def run(&_block)
@@ -81,5 +97,18 @@ module Unleash
       Unleash.logger.error "Streaming client #{self.name} threw exception #{e.class}: '#{e}'"
       Unleash.logger.debug "stacktrace: #{e.backtrace}"
     end
+
+    def read_backup_file!(engine)
+      backup_data = Unleash::BackupFileReader.read!
+      engine.take_state(backup_data) if backup_data
+    end
+
+    def bootstrap(engine)
+      bootstrap_payload = Unleash::Bootstrap::Handler.new(Unleash.configuration.bootstrap_config).retrieve_toggles
+      engine.take_state(bootstrap_payload)
+
+      # reset Unleash.configuration.bootstrap_data to free up memory, as we will never use it again
+      Unleash.configuration.bootstrap_config = nil
+    end
   end
 end

data/lib/unleash/streaming_event_processor.rb

@@ -1,4 +1,5 @@
 require 'json'
+require 'unleash/backup_file_writer'
 
 module Unleash
   class StreamingEventProcessor
@@ -41,7 +42,8 @@ module Unleash
     def handle_updated_event(event)
       handle_delta_event(event.data)
 
-      # TODO: update backup file
+      full_state = @toggle_engine.get_state
+      Unleash::BackupFileWriter.save!(full_state)
     rescue JSON::ParserError => e
       Unleash.logger.error "Unable to parse JSON from streaming event data. Exception thrown #{e.class}: '#{e}'"
       Unleash.logger.debug "stacktrace: #{e.backtrace}"

data/lib/unleash/toggle_fetcher.rb

@@ -1,5 +1,7 @@
 require 'unleash/configuration'
 require 'unleash/bootstrap/handler'
+require 'unleash/backup_file_writer'
+require 'unleash/backup_file_reader'
 require 'net/http'
 require 'json'
 require 'yggdrasil_engine'
@@ -23,10 +25,10 @@ module Unleash
           fetch
         end
       rescue StandardError => e
-        # fail back to reading the backup file
+        # fall back to reading the backup file
         Unleash.logger.warn "ToggleFetcher was unable to fetch from the network, attempting to read from backup file."
         Unleash.logger.debug "Exception Caught: #{e}"
-        read!
+        read_backup_file!
       end
 
       # once initialized, somewhere else you will want to start a loop with fetch()
@@ -54,25 +56,7 @@ module Unleash
       # always synchronize with the local cache when fetching:
       update_engine_state!(response.body)
 
-      save! response.body
-    end
-
-    def save!(toggle_data)
-      Unleash.logger.debug "Will save toggles to disk now"
-
-      backup_file = Unleash.configuration.backup_file
-      backup_file_tmp = "#{backup_file}.tmp"
-
-      self.toggle_lock.synchronize do
-        File.open(backup_file_tmp, "w") do |file|
-          file.write(toggle_data)
-        end
-        File.rename(backup_file_tmp, backup_file)
-      end
-    rescue StandardError => e
-      # This is not really the end of the world. Swallowing the exception.
-      Unleash.logger.error "Unable to save backup file. Exception thrown #{e.class}:'#{e}'"
-      Unleash.logger.error "stacktrace: #{e.backtrace}"
+      Unleash::BackupFileWriter.save! response.body
     end
 
     private
@@ -88,25 +72,9 @@ module Unleash
       Unleash.logger.error "Failed to hydrate state: #{e.backtrace}"
     end
 
-    def read!
-      Unleash.logger.debug "read!()"
-      backup_file = Unleash.configuration.backup_file
-      return nil unless File.exist?(backup_file)
-
-      backup_data = File.read(backup_file)
-      update_engine_state!(backup_data)
-    rescue IOError => e
-      # :nocov:
-      Unleash.logger.error "Unable to read the backup_file: #{e}"
-      # :nocov:
-    rescue JSON::ParserError => e
-      # :nocov:
-      Unleash.logger.error "Unable to parse JSON from existing backup_file: #{e}"
-      # :nocov:
-    rescue StandardError => e
-      # :nocov:
-      Unleash.logger.error "Unable to extract valid data from backup_file. Exception thrown: #{e}"
-      # :nocov:
+    def read_backup_file!
+      backup_data = Unleash::BackupFileReader.read!
+      update_engine_state!(backup_data) if backup_data
     end
 
     def bootstrap

data/lib/unleash/version.rb

@@ -1,3 +1,3 @@
 module Unleash
-  VERSION = "6.4.0".freeze
+  VERSION = "6.5.0".freeze
 end

data/unleash-client.gemspec

@@ -24,12 +24,11 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 2.7"
 
   spec.add_dependency "ld-eventsource", "2.2.4" unless RUBY_ENGINE == 'jruby'
-  spec.add_dependency "yggdrasil-engine", "~> 1.0.4"
+  spec.add_dependency "yggdrasil-engine", "~> 1.2.1"
 
   spec.add_dependency "base64", "~> 0.3.0"
   spec.add_dependency "logger", "~> 1.6"
 
-  spec.add_development_dependency "bundler", "~> 2.1"
   spec.add_development_dependency "rake", "~> 12.3"
   spec.add_development_dependency "rspec", "~> 3.12"
   spec.add_development_dependency "rspec-json_expectations", "~> 2.2"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unleash
 version: !ruby/object:Gem::Version
-  version: 6.4.0
+  version: 6.5.0
 platform: ruby
 authors:
 - Renato Arruda
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-12 00:00:00.000000000 Z
+date: 2026-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ld-eventsource
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.4
+        version: 1.2.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.4
+        version: 1.2.1
 - !ruby/object:Gem::Dependency
   name: base64
   requirement: !ruby/object:Gem::Requirement
@@ -66,20 +66,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.6'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -209,6 +195,8 @@ files:
 - examples/simple.rb
 - examples/streaming.rb
 - lib/unleash.rb
+- lib/unleash/backup_file_reader.rb
+- lib/unleash/backup_file_writer.rb
 - lib/unleash/bootstrap/configuration.rb
 - lib/unleash/bootstrap/handler.rb
 - lib/unleash/bootstrap/provider/base.rb
@@ -217,6 +205,8 @@ files:
 - lib/unleash/client.rb
 - lib/unleash/configuration.rb
 - lib/unleash/context.rb
+- lib/unleash/environment_resolver.rb
+- lib/unleash/impact_metrics.rb
 - lib/unleash/metrics_reporter.rb
 - lib/unleash/scheduled_executor.rb
 - lib/unleash/spec_version.rb