README.md in unleash-4.0.0 vs README.md in unleash-4.1.0
- old
+ new
@@ -1,22 +1,24 @@
# Unleash::Client
-[](https://travis-ci.org/Unleash/unleash-client-ruby)
-[](https://coveralls.io/github/Unleash/unleash-client-ruby?branch=master)
+
+[](https://coveralls.io/github/Unleash/unleash-client-ruby?branch=main)
[](https://badge.fury.io/rb/unleash)
Unleash client so you can roll out your features with confidence.
Leverage the [Unleash Server](https://github.com/Unleash/unleash) for powerful feature toggling in your ruby/rails applications.
## 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
Add this line to your application's Gemfile:
@@ -67,30 +69,35 @@
`app_name` | Name of your program. | Y | String | N/A |
`instance_id` | Identifier for the running instance of program. Important so you can trace back to where metrics are being collected from. **Highly recommended be be set.** | N | String | random UUID |
`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 | {} |
`timeout` | How long to wait for the connection to be established or wait in reading state (open_timeout/read_timeout) | N | Integer | 30 |
`retry_limit` | How many consecutive failures in connecting to the Unleash server are allowed before giving up. Use `Float::INFINITY` if you would like it to never give up. | N | Numeric | 5 |
`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
```ruby
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
unleash_context.user_id = 123
@@ -264,11 +271,67 @@
variant = UNLEASH.get_variant "ColorVariants", @unleash_context, fallback_variant
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
Method Name | Description | Return Type |
---------|-------------|-------------|
`is_enabled?` | Check if feature toggle is to be enabled or not. | Boolean |
@@ -301,10 +364,9 @@
* GradualRolloutSessionIdStrategy
* GradualRolloutUserIdStrategy
* RemoteAddressStrategy
* 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.