unleash 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ce69a2f4588a0d5e459e76aa8d78894497736f484ae20f5d987d50b34aced50
-  data.tar.gz: 24222c2c023197dc4f283ee4e09316f233245b2e82ca4c9ad934fe5519de75d5
+  metadata.gz: 14f988b84b07e45401ad61a5814c1ca44185fc9358cef33f050b1d3bae45dd4e
+  data.tar.gz: afda9cf356088ef976047fe58d38d3b457fb1d8797cb7f519de6bdb953f43267
 SHA512:
-  metadata.gz: 6e056f24c5f840b211f04bc3c605ccf0846d1ff8717cc824d1e50307e636f28c50f91a8fe85f648de9f16377d5441d5feea459a15ad1eae00c35a6238ebb0355
-  data.tar.gz: 51b49947d4aea7d1901bf0083ef366604b5d1cd7859cab1cfaceacc420fb056c4188dd4512c1a7feddc5f9711e0c5ad2660e91c1e681cd57e47307f29948790c
+  metadata.gz: c1ac85ea8b774a230212583b33b9fdab3110fadab2fa1652810ea0913312c1fd20abe4471761b5ccd399d66a52995c0ddb6b803ee42aa4c4432add8a5524e51d
+  data.tar.gz: b03da5caf2bf25683b2d61599a37f15582d26664553ef72096dfd3073aceb96224eaa46fd19c948f9f4fc143e3226ee176a4e66d762016aedf736fb903edae85

data/.github/workflows/pull_request.yml

@@ -15,7 +15,9 @@ jobs:
           - ubuntu
           - macos
         ruby-version:
-          - jruby
+          - jruby-9.2
+          - jruby-9.3
+          - 3.1
           - 3.0
           - 2.7
           - 2.6

data/README.md

@@ -1,7 +1,7 @@
 # Unleash::Client
 
-[![Build Status](https://travis-ci.org/Unleash/unleash-client-ruby.svg?branch=master)](https://travis-ci.org/Unleash/unleash-client-ruby)
-[![Coverage Status](https://coveralls.io/repos/github/Unleash/unleash-client-ruby/badge.svg?branch=master)](https://coveralls.io/github/Unleash/unleash-client-ruby?branch=master)
+![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)
 [![Gem Version](https://badge.fury.io/rb/unleash.svg)](https://badge.fury.io/rb/unleash)
 
 Unleash client so you can roll out your features with confidence.
@@ -10,11 +10,13 @@ Leverage the [Unleash Server](https://github.com/Unleash/unleash) for powerful f
 
 ## Supported Ruby Interpreters
 
+  * MRI 3.1
   * MRI 3.0
   * MRI 2.7
   * MRI 2.6
   * MRI 2.5
-  * jruby
+  * jruby 9.3
+  * jruby 9.2
 
 ## Installation
 
@@ -69,7 +71,7 @@ Argument | Description | Required? |  Type |  Default Value|
 `environment` | Environment the program is running on. Could be for example `prod` or `dev`. Not yet in use. | N | String | `default` |
 `project_name` | Name of the project to retrieve features from. If not set, all feature flags will be retrieved. | N | String | nil |
 `refresh_interval` | How often the unleash client should check with the server for configuration changes. | N | Integer |  15 |
-`metrics_interval` | How often the unleash client should send metrics to server. | N | Integer | 30 |
+`metrics_interval` | How often the unleash client should send metrics to server. | N | Integer | 60 |
 `disable_client` | Disables all communication with the Unleash server, effectively taking it *offline*. If set, `is_enabled?` will always answer with the `default_value` and configuration validation is skipped. Defeats the entire purpose of using unleash, but can be useful in when running tests. | N | Boolean | `false` |
 `disable_metrics` | Disables sending metrics to Unleash server. | N | Boolean | `false` |
 `custom_http_headers` | Custom headers to send to Unleash. As of Unleash v4.0.0, the `Authorization` header is required. For example: `{'Authorization': '<API token>'}` | N | Hash | {} |
@@ -78,9 +80,14 @@ Argument | Description | Required? |  Type |  Default Value|
 `backup_file` | Filename to store the last known state from the Unleash server. Best to not change this from the default. | N | String | `Dir.tmpdir + "/unleash-#{app_name}-repo.json` |
 `logger` | Specify a custom `Logger` class to handle logs for the Unleash client. | N | Class | `Logger.new(STDOUT)` |
 `log_level` | Change the log level for the `Logger` class. Constant from `Logger::Severity`. | N | Constant | `Logger::WARN` |
+`bootstrap_config` | Bootstrap config on how to loaded data on start-up. This is useful for loading large states on startup without (or before) hitting the network. | N | Unleash::Bootstrap::Configuration | `nil` |
 
-For in a more in depth look, please see `lib/unleash/configuration.rb`.
+For a more in-depth look, please see `lib/unleash/configuration.rb`.
 
+Environment Variable | Description
+---------|---------
+`UNLEASH_BOOTSTRAP_FILE` | File to read bootstrap data from
+`UNLEASH_BOOTSTRAP_URL` | URL to read bootstrap data from
 
 ## Usage in a plain Ruby Application
 
@@ -88,7 +95,7 @@ For in a more in depth look, please see `lib/unleash/configuration.rb`.
 require 'unleash'
 require 'unleash/context'
 
-@unleash = Unleash::Client.new(app_name: 'my_ruby_app', url: 'http://unleash.herokuapp.com/api', custom_http_headers: {'Authorization': '<API token>'})
+@unleash = Unleash::Client.new(app_name: 'my_ruby_app', url: 'http://unleash.herokuapp.com/api', custom_http_headers: { 'Authorization': '<API token>' })
 
 feature_name = "AwesomeFeature"
 unleash_context = Unleash::Context.new
@@ -266,6 +273,62 @@ variant = UNLEASH.get_variant "ColorVariants", @unleash_context, fallback_varian
 puts "variant color is: #{variant.payload.fetch('color')}"
 ```
 
+## Bootstrapping
+
+Bootstrap configuration allows the client to be initialized with a predefined set of toggle states. Bootstrapping can be configured by providing a bootstrap configuration when initializing the client.
+```ruby
+@unleash = Unleash::Client.new(
+    url: 'http://unleash.herokuapp.com/api',
+    app_name: 'my_ruby_app',
+    custom_http_headers: { 'Authorization': '<API token>' },
+    bootstrap_config: Unleash::Bootstrap::Configuration.new({
+        url: "http://unleash.herokuapp.com/api/client/features",
+        url_headers: {'Authorization': '<API token>'}
+    })
+)
+```
+The `Bootstrap::Configuration` initializer takes a hash with one of the following options specified:
+
+* `file_path` - An absolute or relative path to a file containing a JSON string of the response body from the Unleash server. This can also be set though the `UNLEASH_BOOTSTRAP_FILE` environment variable.
+* `url` - A url pointing to an Unleash server's features endpoint, the code sample above is illustrative. This can also be set though the `UNLEASH_BOOTSTRAP_URL` environment variable.
+* `url_headers` - Headers for the GET http request to the `url` above. Only used if the `url` parameter is also set. If this option isn't set then the bootstrapper will use the same url headers as the Unleash client.
+* `data` - A raw JSON string as returned by the Unleash server.
+* `block` - A lambda containing custom logic if you need it, an example is provided below.
+
+You should only specify one type of bootstrapping since only one will be invoked and the others will be ignored. The order of preference is as follows:
+
+- Select a data bootstrapper if it exists.
+- If no data bootstrapper exists, select the block bootstrapper.
+- If no block bootstrapper exists, select the file bootstrapper from either parameters or the specified environment variable.
+- If no file bootstrapper exists, then check for a URL bootstrapper from either the parameters or the specified environment variable.
+
+
+Example usage:
+
+First saving the toggles locally:
+```shell
+curl -H 'Authorization: <API token>' -XGET 'http://unleash.herokuapp.com/api' > ./default-toggles.json
+```
+
+Now using them on start up:
+
+```ruby
+
+custom_boostrapper = lambda {
+  File.read('./default-toggles.json')
+}
+
+@unleash = Unleash::Client.new(
+    app_name: 'my_ruby_app',
+    url: 'http://unleash.herokuapp.com/api',
+    custom_http_headers: { 'Authorization': '<API token>' },
+    bootstrap_config: Unleash::Bootstrap::Configuration.new({
+        block: custom_boostrapper
+    }
+)
+```
+
+This example could be easily achieved with a file bootstrapper, this is just to illustrate the usage of custom bootstrapping. Be aware that the client initializer will block until bootstrapping is complete.
 
 #### Client methods
 
@@ -304,7 +367,6 @@ This client comes with the all the required strategies out of the box:
  * UnknownStrategy
  * UserWithIdStrategy
 
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/examples/bootstrap.rb

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+
+require 'unleash'
+require 'unleash/context'
+require 'unleash/bootstrap/configuration'
+
+puts ">> START bootstrap.rb"
+
+@unleash = Unleash::Client.new(
+  url: 'http://unleash.herokuapp.com/api',
+  custom_http_headers: { 'Authorization': '943ca9171e2c884c545c5d82417a655fb77cec970cc3b78a8ff87f4406b495d0' },
+  app_name: 'bootstrap-test',
+  instance_id: 'local-test-cli',
+  refresh_interval: 2,
+  disable_client: true,
+  disable_metrics: true,
+  metrics_interval: 2,
+  retry_limit: 2,
+  bootstrap_config: Unleash::Bootstrap::Configuration.new(file_path: "examples/default-toggles.json")
+)
+
+feature_name = "featureX"
+unleash_context = Unleash::Context.new
+unleash_context.user_id = 123
+
+sleep 1
+3.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
+
+sleep 3
+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 bootstrap.rb"

data/examples/default-toggles.json

@@ -0,0 +1,42 @@
+{
+  "version": 1,
+  "features": [
+    {
+      "name": "featureX",
+      "enabled": true,
+      "strategies": [
+        {
+          "name": "default"
+        }
+      ]
+    },
+    {
+      "name": "featureY",
+      "enabled": false,
+      "strategies": [
+        {
+          "name": "baz",
+          "parameters": {
+            "foo": "bar"
+          }
+        }
+      ]
+    },
+    {
+      "name": "featureZ",
+      "enabled": true,
+      "strategies": [
+        {
+          "name": "default"
+        },
+        {
+          "name": "hola",
+          "parameters": {
+            "name": "val"
+          }
+        }
+      ]
+    }
+  ]
+}
+    

data/lib/unleash/bootstrap/configuration.rb

@@ -0,0 +1,25 @@
+module Unleash
+  module Bootstrap
+    class Configuration
+      attr_accessor :data, :file_path, :url, :url_headers, :block
+
+      def initialize(opts = {})
+        self.file_path = resolve_value_indifferently(opts, 'file_path') || ENV['UNLEASH_BOOTSTRAP_FILE'] || nil
+        self.url = resolve_value_indifferently(opts, 'url') || ENV['UNLEASH_BOOTSTRAP_URL'] || nil
+        self.url_headers = resolve_value_indifferently(opts, 'url_headers')
+        self.data = resolve_value_indifferently(opts, 'data')
+        self.block = resolve_value_indifferently(opts, 'block')
+      end
+
+      def valid?
+        ![self.data, self.file_path, self.url, self.block].all?(&:nil?)
+      end
+
+      private
+
+      def resolve_value_indifferently(opts, key)
+        opts[key] || opts[key.to_sym]
+      end
+    end
+  end
+end

data/lib/unleash/bootstrap/handler.rb

@@ -0,0 +1,22 @@
+require 'unleash/bootstrap/provider/from_url'
+require 'unleash/bootstrap/provider/from_file'
+
+module Unleash
+  module Bootstrap
+    class Handler
+      attr_accessor :configuration
+
+      def initialize(configuration)
+        self.configuration = configuration
+      end
+
+      # @return [String] JSON string representing data returned from an Unleash server
+      def retrieve_toggles
+        return configuration.data unless self.configuration.data.nil?
+        return configuration.block.call if self.configuration.block.is_a?(Proc)
+        return Provider::FromFile.read(configuration.file_path) unless self.configuration.file_path.nil?
+        return Provider::FromUrl.read(configuration.url, configuration.url_headers) unless self.configuration.url.nil?
+      end
+    end
+  end
+end

data/lib/unleash/bootstrap/provider/base.rb

@@ -0,0 +1,14 @@
+module Unleash
+  module Bootstrap
+    module Provider
+      class NotImplemented < RuntimeError
+      end
+
+      class Base
+        def read
+          raise NotImplemented, "Bootstrap is not implemented"
+        end
+      end
+    end
+  end
+end

data/lib/unleash/bootstrap/provider/from_file.rb

@@ -0,0 +1,14 @@
+require 'unleash/bootstrap/provider/base'
+
+module Unleash
+  module Bootstrap
+    module Provider
+      class FromFile < Base
+        # @param file_path [String]
+        def self.read(file_path)
+          File.read(file_path)
+        end
+      end
+    end
+  end
+end

data/lib/unleash/bootstrap/provider/from_url.rb

@@ -0,0 +1,19 @@
+require 'unleash/bootstrap/provider/base'
+
+module Unleash
+  module Bootstrap
+    module Provider
+      class FromUrl < Base
+        # @param url [String]
+        # @param headers [Hash, nil] HTTP headers to use. If not set, the unleash client SDK ones will be used.
+        def self.read(url, headers = nil)
+          response = Unleash::Util::Http.get(URI.parse(url), nil, headers)
+
+          return nil if response.code != '200'
+
+          response.body
+        end
+      end
+    end
+  end
+end

data/lib/unleash/client.rb

@@ -18,8 +18,9 @@ module Unleash
       Unleash.logger = Unleash.configuration.logger.clone
       Unleash.logger.level = Unleash.configuration.log_level
 
+      Unleash.toggle_fetcher = Unleash::ToggleFetcher.new
       if Unleash.configuration.disable_client
-        Unleash.logger.warn "Unleash::Client is disabled! Will only return default results!"
+        Unleash.logger.warn "Unleash::Client is disabled! Will only return default (or bootstrapped if available) results!"
         return
       end
 
@@ -37,11 +38,6 @@ module Unleash
                         default_value_param
                       end
 
-      if Unleash.configuration.disable_client
-        Unleash.logger.warn "unleash_client is disabled! Always returning #{default_value} for feature #{feature}!"
-        return default_value
-      end
-
       toggle_as_hash = Unleash&.toggles&.select{ |toggle| toggle['name'] == feature }&.first
 
       if toggle_as_hash.nil?
@@ -121,11 +117,11 @@ module Unleash
     end
 
     def start_toggle_fetcher
-      Unleash.toggle_fetcher = Unleash::ToggleFetcher.new
       self.fetcher_scheduled_executor = Unleash::ScheduledExecutor.new(
         'ToggleFetcher',
         Unleash.configuration.refresh_interval,
-        Unleash.configuration.retry_limit
+        Unleash.configuration.retry_limit,
+        first_fetch_is_eager
       )
       self.fetcher_scheduled_executor.run do
         Unleash.toggle_fetcher.fetch
@@ -161,5 +157,9 @@ module Unleash
     def disabled_variant
       @disabled_variant ||= Unleash::FeatureToggle.disabled_variant
     end
+
+    def first_fetch_is_eager
+      Unleash.configuration.use_bootstrap?
+    end
   end
 end

data/lib/unleash/configuration.rb

@@ -1,5 +1,6 @@
 require 'securerandom'
 require 'tmpdir'
+require 'unleash/bootstrap/configuration'
 
 module Unleash
   class Configuration
@@ -18,7 +19,8 @@ module Unleash
       :metrics_interval,
       :backup_file,
       :logger,
-      :log_level
+      :log_level,
+      :bootstrap_config
 
     def initialize(opts = {})
       ensure_valid_opts(opts)
@@ -70,6 +72,10 @@ module Unleash
       self.url.delete_suffix '/'
     end
 
+    def use_bootstrap?
+      self.bootstrap_config&.valid?
+    end
+
     private
 
     def ensure_valid_opts(opts)
@@ -87,11 +93,12 @@ module Unleash
       self.disable_client   = false
       self.disable_metrics  = false
       self.refresh_interval = 10
-      self.metrics_interval = 30
+      self.metrics_interval = 60
       self.timeout          = 30
-      self.retry_limit      = 1
+      self.retry_limit      = 5
       self.backup_file      = nil
       self.log_level        = Logger::WARN
+      self.bootstrap_config = nil
 
       self.custom_http_headers = {}
     end

data/lib/unleash/scheduled_executor.rb

@@ -1,19 +1,22 @@
 module Unleash
   class ScheduledExecutor
-    attr_accessor :name, :interval, :max_exceptions, :retry_count, :thread
+    attr_accessor :name, :interval, :max_exceptions, :retry_count, :thread, :immediate_execution
 
-    def initialize(name, interval, max_exceptions = 5)
+    def initialize(name, interval, max_exceptions = 5, immediate_execution = false)
       self.name = name || ''
       self.interval = interval
       self.max_exceptions = max_exceptions
       self.retry_count = 0
       self.thread = nil
+      self.immediate_execution = immediate_execution
     end
 
     def run(&blk)
       self.thread = Thread.new do
         Thread.current[:name] = self.name
 
+        run_blk{ blk.call } if self.immediate_execution
+
         Unleash.logger.debug "thread #{name} loop starting"
         loop do
           Unleash.logger.debug "thread #{name} sleeping for #{interval} seconds"

data/lib/unleash/strategy/remote_address.rb

@@ -13,7 +13,23 @@ module Unleash
         return false unless params.fetch(PARAM, nil).is_a? String
         return false unless context.class.name == 'Unleash::Context'
 
-        params[PARAM].split(',').map(&:strip).include?(context.remote_address)
+        remote_address = ipaddr_or_nil_from_str(context.remote_address)
+
+        params[PARAM]
+          .split(',')
+          .map(&:strip)
+          .map{ |ipblock| ipaddr_or_nil_from_str(ipblock) }
+          .compact
+          .map{ |ipb| ipb.include? remote_address }
+          .any?
+      end
+
+      private
+
+      def ipaddr_or_nil_from_str(ip)
+        IPAddr.new(ip)
+      rescue StandardError
+        nil
       end
     end
   end

data/lib/unleash/toggle_fetcher.rb

@@ -1,4 +1,5 @@
 require 'unleash/configuration'
+require 'unleash/bootstrap/handler'
 require 'net/http'
 require 'json'
 
@@ -13,10 +14,15 @@ module Unleash
       self.toggle_resource = ConditionVariable.new
       self.retry_count = 0
 
-      # start by fetching synchronously, and failing back to reading the backup file.
       begin
-        fetch
+        # if bootstrap configuration is available, initialize. An immediate API read is also triggered
+        if Unleash.configuration.use_bootstrap?
+          bootstrap
+        else
+          fetch
+        end
       rescue StandardError => e
+        # fail 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!
@@ -36,6 +42,8 @@ module Unleash
     # rename to refresh_from_server!  ??
     def fetch
       Unleash.logger.debug "fetch()"
+      return if Unleash.configuration.disable_client
+
       response = Unleash::Util::Http.get(Unleash.configuration.fetch_toggles_uri, etag)
 
       if response.code == '304'
@@ -46,14 +54,7 @@ module Unleash
       end
 
       self.etag = response['ETag']
-      response_hash = JSON.parse(response.body)
-
-      if response_hash['version'] >= 1
-        features = response_hash['features']
-      else
-        raise NotImplemented, "Version of features provided by unleash server" \
-          " is unsupported by this client."
-      end
+      features = get_features(response.body)
 
       # always synchronize with the local cache when fetching:
       synchronize_with_local_cache!(features)
@@ -126,5 +127,23 @@ module Unleash
         file&.close
       end
     end
+
+    def bootstrap
+      bootstrap_payload = Unleash::Bootstrap::Handler.new(Unleash.configuration.bootstrap_config).retrieve_toggles
+      synchronize_with_local_cache! get_features bootstrap_payload
+      update_running_client!
+
+      # reset Unleash.configuration.bootstrap_data to free up memory, as we will never use it again
+      Unleash.configuration.bootstrap_config = nil
+    end
+
+    # @param response_body [String]
+    def get_features(response_body)
+      response_hash = JSON.parse(response_body)
+      return response_hash['features'] if response_hash['version'] >= 1
+
+      raise NotImplemented, "Version of features provided by unleash server" \
+        " is unsupported by this client."
+    end
   end
 end

data/lib/unleash/util/http.rb

@@ -4,10 +4,10 @@ require 'uri'
 module Unleash
   module Util
     module Http
-      def self.get(uri, etag = nil)
+      def self.get(uri, etag = nil, headers_override = nil)
         http = http_connection(uri)
 
-        request = Net::HTTP::Get.new(uri.request_uri, http_headers(etag))
+        request = Net::HTTP::Get.new(uri.request_uri, http_headers(etag, headers_override))
 
         http.request(request)
       end
@@ -30,10 +30,13 @@ module Unleash
         http
       end
 
-      def self.http_headers(etag = nil)
+      # @param etag [String, nil]
+      # @param headers_override [Hash, nil]
+      def self.http_headers(etag = nil, headers_override = nil)
         Unleash.logger.debug "ETag: #{etag}" unless etag.nil?
 
         headers = (Unleash.configuration.http_headers || {}).dup
+        headers = headers_override if headers_override.is_a?(Hash)
         headers['Content-Type'] = 'application/json'
         headers['If-None-Match'] = etag unless etag.nil?
 

data/lib/unleash/version.rb

@@ -1,3 +1,3 @@
 module Unleash
-  VERSION = "4.0.0".freeze
+  VERSION = "4.1.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unleash
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Renato Arruda
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-12-16 00:00:00.000000000 Z
+date: 2022-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: murmurhash3
@@ -157,9 +157,16 @@ files:
 - bin/console
 - bin/setup
 - bin/unleash-client
+- examples/bootstrap.rb
+- examples/default-toggles.json
 - examples/simple.rb
 - lib/unleash.rb
 - lib/unleash/activation_strategy.rb
+- lib/unleash/bootstrap/configuration.rb
+- lib/unleash/bootstrap/handler.rb
+- lib/unleash/bootstrap/provider/base.rb
+- lib/unleash/bootstrap/provider/from_file.rb
+- lib/unleash/bootstrap/provider/from_url.rb
 - lib/unleash/client.rb
 - lib/unleash/configuration.rb
 - lib/unleash/constraint.rb
@@ -204,7 +211,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.3.6
 signing_key: 
 specification_version: 4
 summary: Unleash feature toggle client.