unleash 4.4.4 → 6.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.github/workflows/pull_request.yml +15 -15
- data/.rubocop.yml +5 -1
- data/CHANGELOG.md +147 -1
- data/README.md +161 -144
- data/bin/unleash-client +1 -1
- data/echo_client_spec_version.rb +3 -0
- data/examples/extending_unleash_with_opentelemetry.rb +63 -0
- data/examples/simple.rb +3 -4
- data/examples/streaming.rb +50 -0
- data/lib/unleash/bootstrap/handler.rb +2 -1
- data/lib/unleash/client.rb +47 -26
- data/lib/unleash/configuration.rb +48 -7
- data/lib/unleash/context.rb +35 -9
- data/lib/unleash/metrics_reporter.rb +39 -28
- data/lib/unleash/spec_version.rb +3 -0
- data/lib/unleash/strategies.rb +14 -61
- data/lib/unleash/streaming_client_executor.rb +85 -0
- data/lib/unleash/streaming_event_processor.rb +53 -0
- data/lib/unleash/toggle_fetcher.rb +29 -58
- data/lib/unleash/util/event_source_wrapper.rb +17 -0
- data/lib/unleash/util/http.rb +3 -2
- data/lib/unleash/variant.rb +11 -3
- data/lib/unleash/version.rb +1 -1
- data/lib/unleash.rb +2 -1
- data/unleash-client.gemspec +8 -4
- data/v6_MIGRATION_GUIDE.md +21 -0
- metadata +60 -26
- data/lib/unleash/activation_strategy.rb +0 -31
- data/lib/unleash/constraint.rb +0 -115
- data/lib/unleash/feature_toggle.rb +0 -187
- data/lib/unleash/metrics.rb +0 -41
- data/lib/unleash/strategy/application_hostname.rb +0 -26
- data/lib/unleash/strategy/base.rb +0 -16
- data/lib/unleash/strategy/default.rb +0 -13
- data/lib/unleash/strategy/flexible_rollout.rb +0 -64
- data/lib/unleash/strategy/gradual_rollout_random.rb +0 -24
- data/lib/unleash/strategy/gradual_rollout_sessionid.rb +0 -21
- data/lib/unleash/strategy/gradual_rollout_userid.rb +0 -21
- data/lib/unleash/strategy/remote_address.rb +0 -36
- data/lib/unleash/strategy/user_with_id.rb +0 -20
- data/lib/unleash/strategy/util.rb +0 -16
- data/lib/unleash/variant_definition.rb +0 -26
- data/lib/unleash/variant_override.rb +0 -44
data/README.md
CHANGED
|
@@ -1,31 +1,34 @@
|
|
|
1
1
|
# Unleash::Client
|
|
2
2
|
|
|
3
|
-
|
|
4
|
+
[](https://coveralls.io/github/Unleash/unleash-ruby-sdk?branch=main)
|
|
5
5
|
[](https://badge.fury.io/rb/unleash)
|
|
6
6
|
|
|
7
|
-
Unleash
|
|
7
|
+
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.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
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).
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
> **Migrating to v6**
|
|
12
|
+
>
|
|
13
|
+
> If you use [custom strategies](#custom-strategies) or override built-in ones, read the complete [migration guide](./v6_MIGRATION_GUIDE.md) before upgrading to v6.
|
|
12
14
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
15
|
+
|
|
16
|
+
## Supported Ruby interpreters
|
|
17
|
+
|
|
18
|
+
- MRI 3.4
|
|
19
|
+
- MRI 3.3
|
|
20
|
+
- MRI 3.2
|
|
21
|
+
- MRI 3.1
|
|
22
|
+
- MRI 3.0
|
|
23
|
+
- MRI 2.7
|
|
24
|
+
- jruby 9.4
|
|
22
25
|
|
|
23
26
|
## Installation
|
|
24
27
|
|
|
25
28
|
Add this line to your application's Gemfile:
|
|
26
29
|
|
|
27
30
|
```ruby
|
|
28
|
-
gem 'unleash', '~>
|
|
31
|
+
gem 'unleash', '~> 6.3.0'
|
|
29
32
|
```
|
|
30
33
|
|
|
31
34
|
And then execute:
|
|
@@ -36,85 +39,85 @@ Or install it yourself as:
|
|
|
36
39
|
|
|
37
40
|
$ gem install unleash
|
|
38
41
|
|
|
39
|
-
##
|
|
42
|
+
## Configuration
|
|
40
43
|
|
|
41
44
|
It is **required** to configure:
|
|
42
|
-
- `url` of the unleash server
|
|
43
|
-
- `app_name` with the name of the runninng application.
|
|
44
|
-
- `custom_http_headers` with `{'Authorization': '<API token>'}` when using Unleash v4.0.0 and later.
|
|
45
45
|
|
|
46
|
-
|
|
46
|
+
- `app_name` with the name of the running application
|
|
47
|
+
- `url` of your Unleash server
|
|
48
|
+
- `custom_http_headers` with `{'Authorization': '<YOUR_API_TOKEN>'}` when using Unleash v4+
|
|
47
49
|
|
|
48
50
|
It is **highly recommended** to configure:
|
|
49
|
-
- `instance_id` parameter with a unique identifier for the running instance.
|
|
50
51
|
|
|
52
|
+
- `instance_id` parameter with a unique identifier for the running instance
|
|
51
53
|
|
|
52
54
|
```ruby
|
|
53
55
|
Unleash.configure do |config|
|
|
54
56
|
config.app_name = 'my_ruby_app'
|
|
55
|
-
config.url = '
|
|
56
|
-
config.custom_http_headers = {'Authorization': '<
|
|
57
|
+
config.url = '<YOUR_UNLEASH_URL>/api'
|
|
58
|
+
config.custom_http_headers = {'Authorization': '<YOUR_API_TOKEN>'}
|
|
57
59
|
end
|
|
58
60
|
```
|
|
59
61
|
|
|
60
62
|
or instantiate the client with the valid configuration:
|
|
61
63
|
|
|
62
64
|
```ruby
|
|
63
|
-
UNLEASH = Unleash::Client.new(url: '
|
|
65
|
+
UNLEASH = Unleash::Client.new(url: '<YOUR_UNLEASH_URL>/api', app_name: 'my_ruby_app', custom_http_headers: {'Authorization': '<YOUR_API_TOKEN>'})
|
|
64
66
|
```
|
|
65
67
|
|
|
66
68
|
## Dynamic custom HTTP headers
|
|
67
|
-
|
|
69
|
+
|
|
70
|
+
If you need custom HTTP headers that change during the lifetime of the client, you can pass `custom_http_headers` as a `Proc`.
|
|
68
71
|
|
|
69
72
|
```ruby
|
|
70
73
|
Unleash.configure do |config|
|
|
71
74
|
config.app_name = 'my_ruby_app'
|
|
72
|
-
config.url = '
|
|
75
|
+
config.url = '<YOUR_UNLEASH_URL>/api'
|
|
73
76
|
config.custom_http_headers = proc do
|
|
74
77
|
{
|
|
75
|
-
'Authorization': '<
|
|
78
|
+
'Authorization': '<YOUR_API_TOKEN>',
|
|
76
79
|
'X-Client-Request-Time': Time.now.iso8601
|
|
77
80
|
}
|
|
78
81
|
end
|
|
79
82
|
end
|
|
80
83
|
```
|
|
81
84
|
|
|
82
|
-
#### List of
|
|
83
|
-
|
|
84
|
-
Argument
|
|
85
|
-
|
|
86
|
-
`url`
|
|
87
|
-
`app_name`
|
|
88
|
-
`instance_id`
|
|
89
|
-
`environment`
|
|
90
|
-
`project_name`
|
|
91
|
-
`refresh_interval`
|
|
92
|
-
`metrics_interval`
|
|
93
|
-
`disable_client`
|
|
94
|
-
`disable_metrics`
|
|
95
|
-
`custom_http_headers` | Custom headers to send to Unleash. As of Unleash v4.0.0, the `Authorization` header is required. For example: `{'Authorization': '<
|
|
96
|
-
`timeout`
|
|
97
|
-
`retry_limit`
|
|
98
|
-
`backup_file`
|
|
99
|
-
`logger`
|
|
100
|
-
`log_level`
|
|
101
|
-
`bootstrap_config`
|
|
102
|
-
`strategies`
|
|
85
|
+
#### List of arguments
|
|
86
|
+
|
|
87
|
+
| Argument | Description | Required? | Type | Default value |
|
|
88
|
+
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------- | ---------------------------------------------- |
|
|
89
|
+
| `url` | Unleash server URL. | Y | String | N/A |
|
|
90
|
+
| `app_name` | Name of your program. | Y | String | N/A |
|
|
91
|
+
| `instance_id` | Identifier for the running instance of your program—set this to be able trace where metrics are being collected from. | N | String | random UUID |
|
|
92
|
+
| `environment` | Unleash context option, for example, `prod` or `dev`. Not yet in use. **Not** the same as the SDK's [Unleash environment](https://docs.getunleash.io/reference/environments). | N | String | `default` |
|
|
93
|
+
| `project_name` | Name of the project to retrieve feature flags from. If not set, all feature flags will be retrieved. | N | String | nil |
|
|
94
|
+
| `refresh_interval` | How often the Unleash client should check with the server for configuration changes. | N | Integer | 15 |
|
|
95
|
+
| `metrics_interval` | How often the Unleash client should send metrics to server. | N | Integer | 60 |
|
|
96
|
+
| `disable_client` | Disables all communication with the Unleash server, effectively taking it _offline_. If set, `is_enabled?` always answer with the `default_value` and configuration validation is skipped. Will also forcefully set `disable_metrics` to `true`. Defeats the entire purpose of using Unleash, except when running tests. | N | Boolean | `false` |
|
|
97
|
+
| `disable_metrics` | Disables sending metrics to Unleash server. If the `disable_client` option is set to `true`, then this option will also be set to `true`, regardless of the value provided. | N | Boolean | `false` |
|
|
98
|
+
| `custom_http_headers` | Custom headers to send to Unleash. As of Unleash v4.0.0, the `Authorization` header is required. For example: `{'Authorization': '<YOUR_API_TOKEN>'}`. | N | Hash/Proc | {} |
|
|
99
|
+
| `timeout` | How long to wait for the connection to be established or wait in reading state (open_timeout/read_timeout) | N | Integer | 30 |
|
|
100
|
+
| `retry_limit` | How many consecutive failures in connecting to the Unleash server are allowed before giving up. The default is to retry indefinitely. | N | Float::INFINITY | 5 |
|
|
101
|
+
| `backup_file` | Filename to store the last known state from the Unleash server. It is best to not change this from the default. | N | String | `Dir.tmpdir + "/unleash-#{app_name}-repo.json` |
|
|
102
|
+
| `logger` | Specify a custom `Logger` class to handle logs for the Unleash client. | N | Class | `Logger.new(STDOUT)` |
|
|
103
|
+
| `log_level` | Change the log level for the `Logger` class. Constant from `Logger::Severity`. | N | Constant | `Logger::WARN` |
|
|
104
|
+
| `bootstrap_config` | Bootstrap config for loading data on startup—useful for loading large states on startup without (or before) hitting the network. | N | Unleash::Bootstrap::Configuration | `nil` |
|
|
105
|
+
| `strategies` | Strategies manager that holds all strategies and allows to add custom strategies. | N | Unleash::Strategies | `Unleash::Strategies.new` |
|
|
103
106
|
|
|
104
107
|
For a more in-depth look, please see `lib/unleash/configuration.rb`.
|
|
105
108
|
|
|
106
|
-
Environment Variable
|
|
107
|
-
|
|
108
|
-
`UNLEASH_BOOTSTRAP_FILE` | File to read bootstrap data from
|
|
109
|
-
`UNLEASH_BOOTSTRAP_URL`
|
|
109
|
+
| Environment Variable | Description |
|
|
110
|
+
| ------------------------ | -------------------------------- |
|
|
111
|
+
| `UNLEASH_BOOTSTRAP_FILE` | File to read bootstrap data from |
|
|
112
|
+
| `UNLEASH_BOOTSTRAP_URL` | URL to read bootstrap data from |
|
|
110
113
|
|
|
111
|
-
## Usage in a plain Ruby
|
|
114
|
+
## Usage in a plain Ruby application
|
|
112
115
|
|
|
113
116
|
```ruby
|
|
114
117
|
require 'unleash'
|
|
115
118
|
require 'unleash/context'
|
|
116
119
|
|
|
117
|
-
@unleash = Unleash::Client.new(app_name: 'my_ruby_app', url: '
|
|
120
|
+
@unleash = Unleash::Client.new(app_name: 'my_ruby_app', url: '<YOUR_UNLEASH_URL>/api', custom_http_headers: { 'Authorization': '<YOUR_API_TOKEN>' })
|
|
118
121
|
|
|
119
122
|
feature_name = "AwesomeFeature"
|
|
120
123
|
unleash_context = Unleash::Context.new
|
|
@@ -133,18 +136,23 @@ else
|
|
|
133
136
|
end
|
|
134
137
|
```
|
|
135
138
|
|
|
136
|
-
## Usage in a Rails
|
|
139
|
+
## Usage in a Rails application
|
|
140
|
+
|
|
141
|
+
### 1. Add Initializer
|
|
142
|
+
|
|
143
|
+
The initializer setup varies depending on whether you’re using a standard setup, Puma in clustered mode, Phusion Passenger, or Sidekiq.
|
|
137
144
|
|
|
138
|
-
####
|
|
145
|
+
#### 1.a Initializer for standard Rails applications
|
|
139
146
|
|
|
140
147
|
Put in `config/initializers/unleash.rb`:
|
|
141
148
|
|
|
142
149
|
```ruby
|
|
143
150
|
Unleash.configure do |config|
|
|
144
|
-
config.app_name = Rails.application.class.
|
|
145
|
-
config.url = '
|
|
151
|
+
config.app_name = Rails.application.class.module_parent_name
|
|
152
|
+
config.url = '<YOUR_UNLEASH_URL>'
|
|
146
153
|
# config.instance_id = "#{Socket.gethostname}"
|
|
147
154
|
config.logger = Rails.logger
|
|
155
|
+
config.custom_http_headers = {'Authorization': '<YOUR_API_TOKEN>'}
|
|
148
156
|
end
|
|
149
157
|
|
|
150
158
|
UNLEASH = Unleash::Client.new
|
|
@@ -152,12 +160,12 @@ UNLEASH = Unleash::Client.new
|
|
|
152
160
|
# Or if preferred:
|
|
153
161
|
# Rails.configuration.unleash = Unleash::Client.new
|
|
154
162
|
```
|
|
155
|
-
|
|
156
|
-
For example
|
|
157
|
-
|
|
158
|
-
If it is not set the client will generate an unique UUID for each execution.
|
|
163
|
+
|
|
164
|
+
For `config.instance_id` use a string with a unique identification for the running instance. For example, it could be the hostname if you only run one App per host, or the docker container ID, if you are running in Docker.
|
|
165
|
+
If not set, the client will generate a unique UUID for each execution.
|
|
159
166
|
|
|
160
167
|
To have it available in the `rails console` command as well, also add to the file above:
|
|
168
|
+
|
|
161
169
|
```ruby
|
|
162
170
|
Rails.application.console do
|
|
163
171
|
UNLEASH = Unleash::Client.new
|
|
@@ -166,9 +174,10 @@ Rails.application.console do
|
|
|
166
174
|
end
|
|
167
175
|
```
|
|
168
176
|
|
|
169
|
-
#### Add Initializer if using [Puma in clustered mode](https://github.com/puma/puma#clustered-mode)
|
|
177
|
+
#### 1.b Add Initializer if using [Puma in clustered mode](https://github.com/puma/puma#clustered-mode)
|
|
170
178
|
|
|
171
179
|
That is, multiple workers configured in `puma.rb`:
|
|
180
|
+
|
|
172
181
|
```ruby
|
|
173
182
|
workers ENV.fetch("WEB_CONCURRENCY") { 2 }
|
|
174
183
|
```
|
|
@@ -176,15 +185,16 @@ workers ENV.fetch("WEB_CONCURRENCY") { 2 }
|
|
|
176
185
|
##### with `preload_app!`
|
|
177
186
|
|
|
178
187
|
Then you may keep the client configuration still in `config/initializers/unleash.rb`:
|
|
188
|
+
|
|
179
189
|
```ruby
|
|
180
190
|
Unleash.configure do |config|
|
|
181
191
|
config.app_name = Rails.application.class.parent.to_s
|
|
182
|
-
config.url = '
|
|
183
|
-
config.custom_http_headers = {'Authorization': '<
|
|
192
|
+
config.url = '<YOUR_UNLEASH_URL>/api'
|
|
193
|
+
config.custom_http_headers = {'Authorization': '<YOUR_API_TOKEN>'}
|
|
184
194
|
end
|
|
185
195
|
```
|
|
186
196
|
|
|
187
|
-
But you must ensure that the
|
|
197
|
+
But you must ensure that the Unleash client is instantiated only after the process is forked.
|
|
188
198
|
This is done by creating the client inside the `on_worker_boot` code block in `puma.rb` as below:
|
|
189
199
|
|
|
190
200
|
```ruby
|
|
@@ -206,15 +216,18 @@ end
|
|
|
206
216
|
##### without `preload_app!`
|
|
207
217
|
|
|
208
218
|
By not using `preload_app!`:
|
|
209
|
-
|
|
210
|
-
-
|
|
219
|
+
|
|
220
|
+
- The `Rails` constant will **not** be available.
|
|
221
|
+
- Phased restarts will be possible.
|
|
211
222
|
|
|
212
223
|
You need to ensure that in `puma.rb`:
|
|
213
|
-
|
|
214
|
-
-
|
|
215
|
-
-
|
|
224
|
+
|
|
225
|
+
- The Unleash SDK is loaded with `require 'unleash'` explicitly, as it will not be pre-loaded.
|
|
226
|
+
- All parameters are set explicitly in the `on_worker_boot` block, as `config/initializers/unleash.rb` is not read.
|
|
227
|
+
- There are no references to `Rails` constant, as that is not yet available.
|
|
216
228
|
|
|
217
229
|
Example for `puma.rb`:
|
|
230
|
+
|
|
218
231
|
```ruby
|
|
219
232
|
require 'unleash'
|
|
220
233
|
|
|
@@ -226,8 +239,8 @@ on_worker_boot do
|
|
|
226
239
|
|
|
227
240
|
::UNLEASH = Unleash::Client.new(
|
|
228
241
|
app_name: 'my_rails_app',
|
|
229
|
-
url: '
|
|
230
|
-
custom_http_headers: {'Authorization': '<
|
|
242
|
+
url: '<YOUR_UNLEASH_URL>/api',
|
|
243
|
+
custom_http_headers: {'Authorization': '<YOUR_API_TOKEN>'},
|
|
231
244
|
)
|
|
232
245
|
end
|
|
233
246
|
|
|
@@ -238,9 +251,9 @@ end
|
|
|
238
251
|
|
|
239
252
|
Note that we also added shutdown hooks in `on_worker_shutdown`, to ensure a clean shutdown.
|
|
240
253
|
|
|
241
|
-
#### Add Initializer if using [Phusion Passenger](https://github.com/phusion/passenger)
|
|
254
|
+
#### 1.c Add Initializer if using [Phusion Passenger](https://github.com/phusion/passenger)
|
|
242
255
|
|
|
243
|
-
The
|
|
256
|
+
The Unleash client needs to be configured and instantiated inside the `PhusionPassenger.on_event(:starting_worker_process)` code block due to [smart spawning](https://www.phusionpassenger.com/library/indepth/ruby/spawn_methods/#smart-spawning-caveats):
|
|
244
257
|
|
|
245
258
|
The initializer in `config/initializers/unleash.rb` should look like:
|
|
246
259
|
|
|
@@ -251,8 +264,8 @@ PhusionPassenger.on_event(:starting_worker_process) do |forked|
|
|
|
251
264
|
config.app_name = Rails.application.class.parent.to_s
|
|
252
265
|
# config.instance_id = "#{Socket.gethostname}"
|
|
253
266
|
config.logger = Rails.logger
|
|
254
|
-
config.url = '
|
|
255
|
-
config.custom_http_headers = {'Authorization': '<
|
|
267
|
+
config.url = '<YOUR_UNLEASH_URL>/api'
|
|
268
|
+
config.custom_http_headers = {'Authorization': '<YOUR_API_TOKEN>'}
|
|
256
269
|
end
|
|
257
270
|
|
|
258
271
|
UNLEASH = Unleash::Client.new
|
|
@@ -260,9 +273,9 @@ PhusionPassenger.on_event(:starting_worker_process) do |forked|
|
|
|
260
273
|
end
|
|
261
274
|
```
|
|
262
275
|
|
|
263
|
-
#### Add Initializer hooks when using within [Sidekiq](https://github.com/mperham/sidekiq)
|
|
276
|
+
#### 1.d Add Initializer hooks when using within [Sidekiq](https://github.com/mperham/sidekiq)
|
|
264
277
|
|
|
265
|
-
Note that in this case we require that the code block for `Unleash.configure` is set beforehand.
|
|
278
|
+
Note that in this case, we require that the code block for `Unleash.configure` is set beforehand.
|
|
266
279
|
For example in `config/initializers/unleash.rb`.
|
|
267
280
|
|
|
268
281
|
```ruby
|
|
@@ -277,9 +290,9 @@ Sidekiq.configure_server do |config|
|
|
|
277
290
|
end
|
|
278
291
|
```
|
|
279
292
|
|
|
280
|
-
|
|
293
|
+
### 2. Set Unleash::Context
|
|
281
294
|
|
|
282
|
-
|
|
295
|
+
Add the following method and callback in the application controller to have `@unleash_context` set for all requests:
|
|
283
296
|
|
|
284
297
|
Add in `app/controllers/application_controller.rb`:
|
|
285
298
|
|
|
@@ -296,9 +309,9 @@ Add in `app/controllers/application_controller.rb`:
|
|
|
296
309
|
end
|
|
297
310
|
```
|
|
298
311
|
|
|
299
|
-
|
|
312
|
+
Alternatively, you can add this method only to the controllers that use Unleash.
|
|
300
313
|
|
|
301
|
-
|
|
314
|
+
### 3. Sample usage
|
|
302
315
|
|
|
303
316
|
Then wherever in your application that you need a feature toggle, you can use:
|
|
304
317
|
|
|
@@ -368,15 +381,15 @@ end
|
|
|
368
381
|
```
|
|
369
382
|
|
|
370
383
|
Note:
|
|
371
|
-
|
|
384
|
+
|
|
385
|
+
- The block/lambda/proc can use the feature name and context as arguments.
|
|
372
386
|
- The client will evaluate the fallback function once per call of `is_enabled()`.
|
|
373
|
-
Please keep this in mind when creating your fallback function
|
|
387
|
+
Please keep this in mind when creating your fallback function.
|
|
374
388
|
- The returned value of the block should be a boolean.
|
|
375
|
-
However, the client will coerce the result to boolean via `!!`.
|
|
389
|
+
However, the client will coerce the result to a boolean via `!!`.
|
|
376
390
|
- If both a `default_value` and `fallback_function` are supplied,
|
|
377
391
|
the client will define the default value by `OR`ing the default value and the output of the fallback function.
|
|
378
392
|
|
|
379
|
-
|
|
380
393
|
Alternatively by using `if_enabled` (or `if_disabled`) you can send a code block to be executed as a parameter:
|
|
381
394
|
|
|
382
395
|
```ruby
|
|
@@ -387,9 +400,9 @@ end
|
|
|
387
400
|
|
|
388
401
|
Note: `if_enabled` (and `if_disabled`) only support `default_value`, but not `fallback_function`.
|
|
389
402
|
|
|
390
|
-
|
|
403
|
+
#### Variations
|
|
391
404
|
|
|
392
|
-
If no
|
|
405
|
+
If no flag is found in the server, use the fallback variant.
|
|
393
406
|
|
|
394
407
|
```ruby
|
|
395
408
|
fallback_variant = Unleash::Variant.new(name: 'default', enabled: true, payload: {"color" => "blue"})
|
|
@@ -402,24 +415,26 @@ puts "variant color is: #{variant.payload.fetch('color')}"
|
|
|
402
415
|
|
|
403
416
|
Bootstrap configuration allows the client to be initialized with a predefined set of toggle states.
|
|
404
417
|
Bootstrapping can be configured by providing a bootstrap configuration when initializing the client.
|
|
418
|
+
|
|
405
419
|
```ruby
|
|
406
420
|
@unleash = Unleash::Client.new(
|
|
407
|
-
url: '
|
|
421
|
+
url: '<YOUR_UNLEASH_URL>/api',
|
|
408
422
|
app_name: 'my_ruby_app',
|
|
409
|
-
custom_http_headers: { 'Authorization': '<
|
|
423
|
+
custom_http_headers: { 'Authorization': '<YOUR_API_TOKEN>' },
|
|
410
424
|
bootstrap_config: Unleash::Bootstrap::Configuration.new({
|
|
411
|
-
url: "
|
|
412
|
-
url_headers: {'Authorization': '<
|
|
425
|
+
url: "<YOUR_UNLEASH_URL>/api/client/features",
|
|
426
|
+
url_headers: {'Authorization': '<YOUR_API_TOKEN>'}
|
|
413
427
|
})
|
|
414
428
|
)
|
|
415
429
|
```
|
|
430
|
+
|
|
416
431
|
The `Bootstrap::Configuration` initializer takes a hash with one of the following options specified:
|
|
417
432
|
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
433
|
+
- `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 through the `UNLEASH_BOOTSTRAP_FILE` environment variable.
|
|
434
|
+
- `url` - A url pointing to an Unleash server's features endpoint, the code sample above is illustrative. This can also be set through the `UNLEASH_BOOTSTRAP_URL` environment variable.
|
|
435
|
+
- `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.
|
|
436
|
+
- `data` - A raw JSON string as returned by the Unleash server.
|
|
437
|
+
- `block` - A lambda containing custom logic if you need it, an example is provided below.
|
|
423
438
|
|
|
424
439
|
You should only specify one type of bootstrapping since only one will be invoked and the others will be ignored.
|
|
425
440
|
The order of preference is as follows:
|
|
@@ -429,15 +444,15 @@ The order of preference is as follows:
|
|
|
429
444
|
- If no block bootstrapper exists, select the file bootstrapper from either parameters or the specified environment variable.
|
|
430
445
|
- If no file bootstrapper exists, then check for a URL bootstrapper from either the parameters or the specified environment variable.
|
|
431
446
|
|
|
432
|
-
|
|
433
447
|
Example usage:
|
|
434
448
|
|
|
435
|
-
First
|
|
449
|
+
First, save the toggles locally:
|
|
450
|
+
|
|
436
451
|
```shell
|
|
437
|
-
curl -H 'Authorization: <
|
|
452
|
+
curl -H 'Authorization: <YOUR_API_TOKEN>' -XGET '<YOUR_UNLEASH_URL>/api' > ./default-toggles.json
|
|
438
453
|
```
|
|
439
454
|
|
|
440
|
-
|
|
455
|
+
Then use them on startup:
|
|
441
456
|
|
|
442
457
|
```ruby
|
|
443
458
|
|
|
@@ -447,8 +462,8 @@ custom_boostrapper = lambda {
|
|
|
447
462
|
|
|
448
463
|
@unleash = Unleash::Client.new(
|
|
449
464
|
app_name: 'my_ruby_app',
|
|
450
|
-
url: '
|
|
451
|
-
custom_http_headers: { 'Authorization': '<
|
|
465
|
+
url: '<YOUR_UNLEASH_URL>/api',
|
|
466
|
+
custom_http_headers: { 'Authorization': '<YOUR_API_TOKEN>' },
|
|
452
467
|
bootstrap_config: Unleash::Bootstrap::Configuration.new({
|
|
453
468
|
block: custom_boostrapper
|
|
454
469
|
})
|
|
@@ -460,19 +475,19 @@ Be aware that the client initializer will block until bootstrapping is complete.
|
|
|
460
475
|
|
|
461
476
|
#### Client methods
|
|
462
477
|
|
|
463
|
-
Method
|
|
464
|
-
|
|
465
|
-
`is_enabled?`
|
|
466
|
-
`enabled?`
|
|
467
|
-
`if_enabled`
|
|
468
|
-
`is_disabled?` |
|
|
469
|
-
`disabled?`
|
|
470
|
-
`if_disabled`
|
|
471
|
-
`get_variant`
|
|
472
|
-
`shutdown`
|
|
473
|
-
`shutdown!`
|
|
478
|
+
| Method name | Description | Return type |
|
|
479
|
+
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
|
|
480
|
+
| `is_enabled?` | Checks if a feature toggle is enabled or not | Boolean |
|
|
481
|
+
| `enabled?` | A more idiomatic Ruby alias for the `is_enabled?` method | Boolean |
|
|
482
|
+
| `if_enabled` | Runs a code block, if a feature is enabled | `yield` |
|
|
483
|
+
| `is_disabled?` | Checks if feature toggle is enabled or not | Boolean |
|
|
484
|
+
| `disabled?` | A more idiomatic Ruby alias for the `is_disabled?` method | Boolean |
|
|
485
|
+
| `if_disabled` | Runs a code block, if a feature is disabled | `yield` |
|
|
486
|
+
| `get_variant` | Gets variant for a given feature | `Unleash::Variant` |
|
|
487
|
+
| `shutdown` | Saves metrics to disk, flushes metrics to server, and then kills `ToggleFetcher` and `MetricsReporter` threads—a safe shutdown, not generally needed in long-running applications, like web applications | nil |
|
|
488
|
+
| `shutdown!` | Kills `ToggleFetcher` and `MetricsReporter` threads immediately | nil |
|
|
474
489
|
|
|
475
|
-
For the full method signatures,
|
|
490
|
+
For the full method signatures, see [client.rb](lib/unleash/client.rb).
|
|
476
491
|
|
|
477
492
|
## Local test client
|
|
478
493
|
|
|
@@ -484,24 +499,24 @@ bundle exec bin/unleash-client --help
|
|
|
484
499
|
bundle exec examples/simple.rb
|
|
485
500
|
```
|
|
486
501
|
|
|
487
|
-
## Available
|
|
502
|
+
## Available strategies
|
|
488
503
|
|
|
489
|
-
This client comes with
|
|
504
|
+
This client comes with all the required strategies out of the box:
|
|
490
505
|
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
506
|
+
- ApplicationHostnameStrategy
|
|
507
|
+
- DefaultStrategy
|
|
508
|
+
- FlexibleRolloutStrategy
|
|
509
|
+
- GradualRolloutRandomStrategy
|
|
510
|
+
- GradualRolloutSessionIdStrategy
|
|
511
|
+
- GradualRolloutUserIdStrategy
|
|
512
|
+
- RemoteAddressStrategy
|
|
513
|
+
- UnknownStrategy
|
|
514
|
+
- UserWithIdStrategy
|
|
500
515
|
|
|
501
|
-
## Custom
|
|
516
|
+
## Custom strategies
|
|
502
517
|
|
|
503
|
-
|
|
504
|
-
In order for strategy to work correctly it should support two methods `name` and `is_enabled
|
|
518
|
+
You can add [custom activation strategies](https://docs.getunleash.io/advanced/custom_activation_strategy) using configuration.
|
|
519
|
+
In order for the strategy to work correctly it should support two methods `name` and `is_enabled?`.
|
|
505
520
|
|
|
506
521
|
```ruby
|
|
507
522
|
class MyCustomStrategy
|
|
@@ -522,36 +537,38 @@ end
|
|
|
522
537
|
## Development
|
|
523
538
|
|
|
524
539
|
After checking out the repo, run `bin/setup` to install dependencies.
|
|
525
|
-
Then, run `rake spec` to run the tests.
|
|
540
|
+
Then, run `bundle exec rake spec` to run the tests.
|
|
526
541
|
You can also run `bin/console` for an interactive prompt that will allow you to experiment.
|
|
527
542
|
|
|
528
543
|
This SDK is also built against the Unleash Client Specification tests.
|
|
529
544
|
To run the Ruby SDK against this test suite, you'll need to have a copy on your machine, you can clone the repository directly using:
|
|
530
545
|
|
|
531
|
-
`git clone --
|
|
546
|
+
`git clone --branch v$(ruby echo_client_spec_version.rb) https://github.com/Unleash/client-specification.git`
|
|
532
547
|
|
|
533
|
-
After doing this, `rake spec` will also run the client specification tests.
|
|
548
|
+
After doing this, `bundle exec rake spec` will also run the client specification tests.
|
|
534
549
|
|
|
535
550
|
To install this gem onto your local machine, run `bundle exec rake install`.
|
|
536
551
|
|
|
537
552
|
## Releasing
|
|
538
553
|
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
- update the version number in [./lib/unleash/version.rb](./lib/unleash/version.rb),
|
|
542
|
-
- if a major or minor version bump, update the [Installation section](#Installation) in [README.md](README.md)
|
|
543
|
-
- update [CHANGELOG.md](CHANGELOG.md) following the format on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
|
|
544
|
-
- commit with message `chore: bump version to x.y.z`
|
|
545
|
-
- then run `bundle exec rake release`
|
|
546
|
-
- This will create a git tag for the version on the current commit,
|
|
547
|
-
- push git commits and tags to origin and
|
|
548
|
-
- push the `.gem` file to [rubygems.org](https://rubygems.org)
|
|
554
|
+
To release a new version, follow these steps:
|
|
549
555
|
|
|
556
|
+
1. Update version number:
|
|
557
|
+
- Increment the version number in the `./lib/unleash/version.rb` file according to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) guidelines.
|
|
558
|
+
2. Update documentation:
|
|
559
|
+
- If the update includes a major or minor version change, update the [Installation section](#installation) in [README.md](README.md).
|
|
560
|
+
- Update [CHANGELOG.md](CHANGELOG.md) following the format on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
|
561
|
+
3. Commit changes:
|
|
562
|
+
- Commit the changes with a message like: `chore: bump version to x.y.z.`
|
|
563
|
+
4. Release the gem:
|
|
564
|
+
- On the `main` branch, run `bundle exec rake release` to create a git tag for the new version, push commits and tags to origin, and publish `.gem` file to [rubygems.org](https://rubygems.org).
|
|
550
565
|
|
|
551
566
|
## Contributing
|
|
552
567
|
|
|
553
|
-
Bug reports and pull requests are welcome on GitHub at https://github.com/unleash/unleash-
|
|
568
|
+
Bug reports and pull requests are welcome on GitHub at https://github.com/unleash/unleash-ruby-sdk.
|
|
554
569
|
|
|
555
570
|
Be sure to run both `bundle exec rspec` and `bundle exec rubocop` in your branch before creating a pull request.
|
|
556
571
|
|
|
557
572
|
Please include tests with any pull requests, to avoid regressions.
|
|
573
|
+
|
|
574
|
+
Check out our guide for more information on how to build and scale [feature flag systems](https://docs.getunleash.io/topics/feature-flags/feature-flag-best-practices).
|
data/bin/unleash-client
CHANGED
|
@@ -77,7 +77,7 @@ log_level = \
|
|
|
77
77
|
|
|
78
78
|
@unleash = Unleash::Client.new(
|
|
79
79
|
url: options[:url],
|
|
80
|
-
app_name: 'unleash-
|
|
80
|
+
app_name: 'unleash-ruby-sdk-cli',
|
|
81
81
|
disable_metrics: options[:metrics],
|
|
82
82
|
custom_http_headers: options[:custom_http_headers],
|
|
83
83
|
log_level: log_level
|