unleash 6.3.1 → 6.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9c5d4638648ffd4a6891f6b6f851437028af770b417d020b6ae852f24d5ead7
-  data.tar.gz: 9933cfff16b53947a37385f0193dd61b6955d9010865cb9ad02e193d3363afdf
+  metadata.gz: a76eb26bedcade3ed88389aa909f7ead99177e336509bc4fd99d85c4703f1405
+  data.tar.gz: 43410bf468ac4fd3b56af79a354eb84794c40c67b6c2d96c27bdf26772b1c54d
 SHA512:
-  metadata.gz: 4f0ab91b15331353b5d3024f102a9915c68c62471da230057c363dfbd0098b14619ec0df7cc63a5aec906760d25f5dcd70af7f6490c57e7f1ada3a1878eaac9c
-  data.tar.gz: 3bf0dd46e6f23715e5495fd3fcf09940cd39722d32d938730102a45661813efefc164bb3e84b55410db753e5531b4e57bdea3476ad263500d8a077f832e968ca
+  metadata.gz: 3e43cbef4ba85e84265f10b9414eba95c92aeb59792a40318e15df37313ee5a6b99ce3c3e3e89d465c56e40fff92e61ed4115766d59b6ee9147c2d2c5920ebf7
+  data.tar.gz: 2401fa3bf2d0f824d7da3cf2e01cc4c20fe740f26d2019f89554adbbc67fdc5c0f4fa65003e143391b14ea2466314db36852edd0ccefca8178f6545e3186170d

data/CHANGELOG.md

@@ -13,7 +13,15 @@ Note: These changes are not considered notable:
 
 ## [Unreleased]
 
-## [6.3.0] - 2025-05-27
+## [6.4.0] - 2025-08-12
+### Added
+- Experimental streaming support
+
+#### Changed
+- SDK registration name
+- base64 dependency version
+
+## [6.3.1] - 2025-05-27
 ### Fixed
 - Upgraded Yggdrasil engine to fix a memory leak in metrics.
 

data/README.md

@@ -1,10 +1,12 @@
 # Unleash::Client
 
-![Build Status](https://github.com/Unleash/unleash-client-ruby/actions/workflows/pull_request.yml/badge.svg?branch=main)
-[![Coverage Status](https://coveralls.io/repos/github/Unleash/unleash-client-ruby/badge.svg?branch=main)](https://coveralls.io/github/Unleash/unleash-client-ruby?branch=main)
+![Build Status](https://github.com/Unleash/unleash-ruby-sdk/actions/workflows/pull_request.yml/badge.svg?branch=main)
+[![Coverage Status](https://coveralls.io/repos/github/Unleash/unleash-ruby-sdk/badge.svg?branch=main)](https://coveralls.io/github/Unleash/unleash-ruby-sdk?branch=main)
 [![Gem Version](https://badge.fury.io/rb/unleash.svg)](https://badge.fury.io/rb/unleash)
 
-Ruby client for the [Unleash](https://github.com/Unleash/unleash) feature management service.
+Unleash is a private, secure, and scalable [feature management platform](https://www.getunleash.io/) built to reduce the risk of releasing new features and accelerate software development. This Ruby SDK is designed to help you integrate with Unleash and evaluate feature flags inside your application.
+
+You can use this client with [Unleash Enterprise](https://www.getunleash.io/pricing?utm_source=readme&utm_medium=ruby) or [Unleash Open Source](https://github.com/Unleash/unleash).
 
 >  **Migrating to v6**
 >
@@ -563,7 +565,7 @@ To release a new version, follow these steps:
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/unleash/unleash-client-ruby.
+Bug reports and pull requests are welcome on GitHub at https://github.com/unleash/unleash-ruby-sdk.
 
 Be sure to run both `bundle exec rspec` and `bundle exec rubocop` in your branch before creating a pull request.
 

data/bin/unleash-client

@@ -77,7 +77,7 @@ log_level = \
 
 @unleash = Unleash::Client.new(
   url: options[:url],
-  app_name: 'unleash-client-ruby-cli',
+  app_name: 'unleash-ruby-sdk-cli',
   disable_metrics: options[:metrics],
   custom_http_headers: options[:custom_http_headers],
   log_level: log_level

data/examples/simple.rb

@@ -18,8 +18,8 @@ puts ">> START simple.rb"
 # or:
 
 @unleash = Unleash::Client.new(
-  url: 'https://unleash.herokuapp.com/api',
-  custom_http_headers: { 'Authorization': '943ca9171e2c884c545c5d82417a655fb77cec970cc3b78a8ff87f4406b495d0' },
+  url: 'https://app.unleash-hosted.com/demo/api',
+  custom_http_headers: { 'Authorization': 'demo-app:dev.9fc74dd72d2b88bea5253c04240b21a54841f08d9918046ed55a06b5' },
   app_name: 'simple-test',
   instance_id: 'local-test-cli',
   refresh_interval: 2,
@@ -27,8 +27,7 @@ puts ">> START simple.rb"
   retry_limit: 2
 )
 
-# feature_name = "AwesomeFeature"
-feature_name = "4343443"
+feature_name = "example-flag"
 unleash_context = Unleash::Context.new
 unleash_context.user_id = 123
 

data/examples/streaming.rb

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+
+require 'unleash'
+require 'unleash/context'
+
+puts ">> START streaming.rb"
+
+@unleash = Unleash::Client.new(
+  url: 'https://app.unleash-hosted.com/demo/api',
+  custom_http_headers: { 'Authorization': 'demo-app:dev.9fc74dd72d2b88bea5253c04240b21a54841f08d9918046ed55a06b5' },
+  app_name: 'streaming-test',
+  instance_id: 'local-streaming-cli',
+  refresh_interval: 2,
+  metrics_interval: 2,
+  retry_limit: 2,
+  experimental_mode: { type: 'streaming' },
+  timeout: 5,
+  log_level: Logger::DEBUG
+)
+
+feature_name = "example-flag"
+unleash_context = Unleash::Context.new
+unleash_context.user_id = 123
+
+puts "Waiting for client to initialize..."
+sleep 2
+
+100.times do
+  if @unleash.is_enabled?(feature_name, unleash_context)
+    puts "> #{feature_name} is enabled"
+  else
+    puts "> #{feature_name} is not enabled"
+  end
+  sleep 1
+  puts "---"
+  puts ""
+  puts ""
+end
+feature_name = "foobar"
+if @unleash.is_enabled?(feature_name, unleash_context, true)
+  puts "> #{feature_name} is enabled"
+else
+  puts "> #{feature_name} is not enabled"
+end
+
+puts "> shutting down client..."
+
+@unleash.shutdown
+
+puts ">> END streaming.rb"

data/lib/unleash/client.rb

@@ -2,8 +2,10 @@ require 'unleash/configuration'
 require 'unleash/toggle_fetcher'
 require 'unleash/metrics_reporter'
 require 'unleash/scheduled_executor'
+require 'unleash/streaming_client_executor'
 require 'unleash/variant'
 require 'unleash/util/http'
+require 'unleash/util/event_source_wrapper'
 require 'logger'
 require 'time'
 
@@ -21,7 +23,8 @@ module Unleash
       Unleash.engine = YggdrasilEngine.new
       Unleash.engine.register_custom_strategies(Unleash.configuration.strategies.custom_strategies)
 
-      Unleash.toggle_fetcher = Unleash::ToggleFetcher.new Unleash.engine
+      Unleash.toggle_fetcher = Unleash::ToggleFetcher.new Unleash.engine unless Unleash.configuration.streaming_mode?
+
       if Unleash.configuration.disable_client
         Unleash.logger.warn "Unleash::Client is disabled! Will only return default (or bootstrapped if available) results!"
         Unleash.logger.warn "Unleash::Client is disabled! Metrics and MetricsReporter are also disabled!"
@@ -30,7 +33,9 @@ module Unleash
       end
 
       register
-      start_toggle_fetcher
+
+      initialize_client_mode
+
       start_metrics unless Unleash.configuration.disable_metrics
     end
     # rubocop:enable Metrics/AbcSize
@@ -105,7 +110,7 @@ module Unleash
     # quick shutdown: just kill running threads
     def shutdown!
       unless Unleash.configuration.disable_client
-        self.fetcher_scheduled_executor.exit
+        self.fetcher_scheduled_executor&.exit
         self.metrics_scheduled_executor.exit unless Unleash.configuration.disable_metrics
       end
     end
@@ -117,7 +122,7 @@ module Unleash
         'appName': Unleash.configuration.app_name,
         'instanceId': Unleash.configuration.instance_id,
         'connectionId': Unleash.configuration.connection_id,
-        'sdkVersion': "unleash-client-ruby:" + Unleash::VERSION,
+        'sdkVersion': "unleash-ruby-sdk:" + Unleash::VERSION,
         'strategies': Unleash.strategies.known_strategies,
         'started': Time.now.iso8601(Unleash::TIME_RESOLUTION),
         'interval': Unleash.configuration.metrics_interval_in_millis,
@@ -140,6 +145,11 @@ module Unleash
       end
     end
 
+    def start_streaming_client
+      self.fetcher_scheduled_executor = Unleash::StreamingClientExecutor.new('StreamingExecutor', Unleash.engine)
+      self.fetcher_scheduled_executor.run
+    end
+
     def start_metrics
       Unleash.reporter = Unleash::MetricsReporter.new
       self.metrics_scheduled_executor = Unleash::ScheduledExecutor.new(
@@ -172,5 +182,13 @@ module Unleash
     def first_fetch_is_eager
       Unleash.configuration.use_bootstrap?
     end
+
+    def initialize_client_mode
+      if Unleash.configuration.streaming_mode?
+        start_streaming_client
+      else
+        start_toggle_fetcher
+      end
+    end
   end
 end

data/lib/unleash/configuration.rb

@@ -22,7 +22,8 @@ module Unleash
       :log_level,
       :bootstrap_config,
       :strategies,
-      :use_delta_api
+      :use_delta_api,
+      :experimental_mode
     attr_reader :connection_id
 
     def initialize(opts = {})
@@ -57,7 +58,7 @@ module Unleash
         'UNLEASH-INSTANCEID' => self.instance_id,
         'UNLEASH-APPNAME' => self.app_name,
         'Unleash-Client-Spec' => CLIENT_SPECIFICATION_VERSION,
-        'UNLEASH-SDK' => "unleash-client-ruby:#{Unleash::VERSION}"
+        'UNLEASH-SDK' => "unleash-ruby-sdk:#{Unleash::VERSION}"
       }.merge!(generate_custom_http_headers)
       headers['UNLEASH-CONNECTION-ID'] = @connection_id
       headers
@@ -67,7 +68,9 @@ module Unleash
       uri = nil
       ## Personal feeling but Rubocop's suggestion here is too dense to be properly readable
       # rubocop:disable Style/ConditionalAssignment
-      if self.use_delta_api
+      if streaming_mode?
+        uri = URI("#{self.url_stripped_of_slash}/client/streaming")
+      elsif self.use_delta_api || polling_with_delta?
         uri = URI("#{self.url_stripped_of_slash}/client/delta")
       else
         uri = URI("#{self.url_stripped_of_slash}/client/features")
@@ -93,6 +96,17 @@ module Unleash
       self.bootstrap_config&.valid?
     end
 
+    def streaming_mode?
+      validate_streaming_support! if streaming_configured?
+      streaming_configured?
+    end
+
+    def polling_with_delta?
+      self.experimental_mode.is_a?(Hash) &&
+        self.experimental_mode[:type] == 'polling' &&
+        self.experimental_mode[:format] == 'delta'
+    end
+
     private
 
     def set_defaults
@@ -112,6 +126,7 @@ module Unleash
       self.bootstrap_config = nil
       self.strategies       = Unleash::Strategies.new
       self.use_delta_api    = false
+      self.experimental_mode = nil
 
       self.custom_http_headers = {}
       @connection_id = SecureRandom.uuid
@@ -149,5 +164,15 @@ module Unleash
     rescue NoMethodError
       raise ArgumentError, "unknown configuration parameter '#{val}'"
     end
+
+    def streaming_configured?
+      self.experimental_mode.is_a?(Hash) && self.experimental_mode[:type] == 'streaming'
+    end
+
+    def validate_streaming_support!
+      return unless RUBY_ENGINE == 'jruby'
+
+      raise "Streaming mode is not supported on JRuby. Please use polling mode instead or switch to MRI/CRuby."
+    end
   end
 end

data/lib/unleash/streaming_client_executor.rb

@@ -0,0 +1,85 @@
+require 'unleash/streaming_event_processor'
+require 'unleash/util/event_source_wrapper'
+
+module Unleash
+  class StreamingClientExecutor
+    attr_accessor :name, :event_source, :event_processor, :running
+
+    def initialize(name, engine)
+      self.name = name || 'StreamingClientExecutor'
+      self.event_source = nil
+      self.event_processor = Unleash::StreamingEventProcessor.new(engine)
+      self.running = false
+    end
+
+    def run(&_block)
+      start
+    end
+
+    def start
+      return if self.running || Unleash.configuration.disable_client
+
+      Unleash.logger.debug "Streaming client #{self.name} starting connection to: #{Unleash.configuration.fetch_toggles_uri}"
+
+      self.event_source = create_event_source
+      setup_event_handlers
+
+      self.running = true
+      Unleash.logger.debug "Streaming client #{self.name} connection established"
+    end
+
+    def stop
+      return unless self.running
+
+      Unleash.logger.debug "Streaming client #{self.name} stopping connection"
+      self.running = false
+      self.event_source&.close
+      self.event_source = nil
+      Unleash.logger.debug "Streaming client #{self.name} connection closed"
+    end
+
+    alias exit stop
+
+    def running?
+      self.running
+    end
+
+    private
+
+    def create_event_source
+      sse_client = Unleash::Util::EventSourceWrapper.client
+      if sse_client.nil?
+        raise "Streaming mode is configured but EventSource client is not available. " \
+              "Please install the 'ld-eventsource' gem or switch to polling mode."
+      end
+
+      headers = (Unleash.configuration.http_headers || {}).dup
+
+      sse_client.new(
+        Unleash.configuration.fetch_toggles_uri.to_s,
+        headers: headers,
+        read_timeout: 60,
+        reconnect_time: 2,
+        connect_timeout: 10,
+        logger: Unleash.logger
+      )
+    end
+
+    def setup_event_handlers
+      self.event_source.on_event do |event|
+        handle_event(event)
+      end
+
+      self.event_source.on_error do |error|
+        Unleash.logger.warn "Streaming client #{self.name} error: #{error}"
+      end
+    end
+
+    def handle_event(event)
+      self.event_processor.process_event(event)
+    rescue StandardError => e
+      Unleash.logger.error "Streaming client #{self.name} threw exception #{e.class}: '#{e}'"
+      Unleash.logger.debug "stacktrace: #{e.backtrace}"
+    end
+  end
+end

data/lib/unleash/streaming_event_processor.rb

@@ -0,0 +1,53 @@
+require 'json'
+
+module Unleash
+  class StreamingEventProcessor
+    attr_accessor :toggle_engine, :mutex
+
+    def initialize(toggle_engine)
+      self.toggle_engine = toggle_engine
+      self.mutex = Mutex.new
+    end
+
+    def process_event(event)
+      case event.type.to_s
+      when 'unleash-connected'
+        Unleash.logger.debug "Streaming client connected"
+        handle_connected_event(event)
+      when 'unleash-updated'
+        Unleash.logger.debug "Received streaming update"
+        handle_updated_event(event)
+      else
+        Unleash.logger.debug "Received unknown event type: #{event.type}"
+      end
+    rescue StandardError => e
+      Unleash.logger.error "Error handling streaming event threw exception #{e.class}: '#{e}'"
+      Unleash.logger.debug "stacktrace: #{e.backtrace}"
+    end
+
+    def handle_delta_event(event_data)
+      self.mutex.synchronize do
+        self.toggle_engine.take_state(event_data)
+      end
+    end
+
+    private
+
+    def handle_connected_event(event)
+      Unleash.logger.debug "Processing initial hydration data"
+      handle_updated_event(event)
+    end
+
+    def handle_updated_event(event)
+      handle_delta_event(event.data)
+
+      # TODO: update backup file
+    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}"
+    rescue StandardError => e
+      Unleash.logger.error "Error processing delta update threw exception #{e.class}: '#{e}'"
+      Unleash.logger.debug "stacktrace: #{e.backtrace}"
+    end
+  end
+end

data/lib/unleash/util/event_source_wrapper.rb

@@ -0,0 +1,17 @@
+module Unleash
+  module Util
+    module EventSourceWrapper
+      def self.client
+        return nil if RUBY_ENGINE == 'jruby'
+
+        begin
+          require 'ld-eventsource'
+          SSE::Client
+        rescue LoadError => e
+          Unleash.logger.error "Failed to load ld-eventsource: #{e.message}"
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/unleash/version.rb

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

data/unleash-client.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |spec|
   spec.description   = "This is the ruby client for Unleash, a powerful feature toggle system
     that gives you a great overview over all feature toggles across all your applications and services."
 
-  spec.homepage      = "https://github.com/unleash/unleash-client-ruby"
+  spec.homepage      = "https://github.com/unleash/unleash-ruby-sdk"
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
@@ -23,9 +23,10 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
   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 "base64", "~> 0.2.0"
+  spec.add_dependency "base64", "~> 0.3.0"
   spec.add_dependency "logger", "~> 1.6"
 
   spec.add_development_dependency "bundler", "~> 2.1"

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: unleash
 version: !ruby/object:Gem::Version
-  version: 6.3.1
+  version: 6.4.0
 platform: ruby
 authors:
 - Renato Arruda
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-27 00:00:00.000000000 Z
+date: 2025-08-12 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ld-eventsource
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.2.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.2.4
 - !ruby/object:Gem::Dependency
   name: yggdrasil-engine
   requirement: !ruby/object:Gem::Requirement
@@ -30,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.3.0
 - !ruby/object:Gem::Dependency
   name: logger
   requirement: !ruby/object:Gem::Requirement
@@ -193,6 +207,7 @@ files:
 - examples/default-toggles.json
 - examples/extending_unleash_with_opentelemetry.rb
 - examples/simple.rb
+- examples/streaming.rb
 - lib/unleash.rb
 - lib/unleash/bootstrap/configuration.rb
 - lib/unleash/bootstrap/handler.rb
@@ -206,17 +221,20 @@ files:
 - lib/unleash/scheduled_executor.rb
 - lib/unleash/spec_version.rb
 - lib/unleash/strategies.rb
+- lib/unleash/streaming_client_executor.rb
+- lib/unleash/streaming_event_processor.rb
 - lib/unleash/toggle_fetcher.rb
+- lib/unleash/util/event_source_wrapper.rb
 - lib/unleash/util/http.rb
 - lib/unleash/variant.rb
 - lib/unleash/version.rb
 - unleash-client.gemspec
 - v6_MIGRATION_GUIDE.md
-homepage: https://github.com/unleash/unleash-client-ruby
+homepage: https://github.com/unleash/unleash-ruby-sdk
 licenses:
 - Apache-2.0
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -231,8 +249,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.6
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Unleash feature toggle client.
 test_files: []