confset 1.0.0 → 1.0.1
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/{docs/CHANGELOG.md → CHANGELOG.md} +7 -0
- data/{docs/LICENSE.md → LICENSE.md} +0 -0
- data/README.md +649 -0
- data/lib/confset/options.rb +0 -1
- data/lib/confset/sources/env_source.rb +10 -8
- data/lib/confset/version.rb +1 -1
- data/lib/confset.rb +14 -0
- data/spec/config_env_spec.rb +0 -11
- data/spec/spec_helper.rb +1 -0
- metadata +22 -7
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 9b6d8777cb97c4f2de9b0586089b47f4a2aa27318179f920695a27bc06827af2
|
4
|
+
data.tar.gz: 3ad5dd305f8ab4f75eda0ad714850e0f1ef99c14c14ca891204e7a517563557d
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: f41892256c646110e5c53d4de461dd22770abb9ef2c13e613df1eeff1ae2fc9f68b7155f8cafd7abdb751052b5c752b8e918c8f2858a847d4f8758d0742fa36a
|
7
|
+
data.tar.gz: 24a5afc264bcaa53377a0a67deb12d74b9fb83c015ed6fafb7373534500937fce2c3d657df2f77ab388e549bc46c0ef1f260a3385cf47758ea77aa3e9c36caa0
|
@@ -1,5 +1,12 @@
|
|
1
1
|
# Changelog
|
2
2
|
|
3
|
+
## v1.0.1-20220530 - [Danilo Carolino](@danilogco)
|
4
|
+
|
5
|
+
Fixes
|
6
|
+
|
7
|
+
* Avoid to crash the Rails application when there is an error
|
8
|
+
parsing a variable <https://github.com/dcotecnologia/confset/pull/5>
|
9
|
+
|
3
10
|
## v1.0.0-20220527 - [Danilo Carolino](@danilogco)
|
4
11
|
|
5
12
|
Initial release
|
File without changes
|
data/README.md
ADDED
@@ -0,0 +1,649 @@
|
|
1
|
+
# Confset
|
2
|
+
|
3
|
+
[](https://badge.fury.io/rb/confset)
|
4
|
+
[](https://rubygems.org/gems/confset)
|
5
|
+
[](https://github.com/dcotecnologia/confset/actions/workflows/tests.yml)
|
6
|
+
[](https://github.com/dcotecnologia/confset/actions/workflows/codeql.yml)
|
7
|
+
[](https://github.com/dcotecnologia/confset/actions/workflows/release.yml)
|
8
|
+
|
9
|
+
## Summary
|
10
|
+
|
11
|
+
Confset helps you easily manage environment specific settings in an easy and
|
12
|
+
usable manner.
|
13
|
+
|
14
|
+
This project is a fork of <https://github.com/rubyconfig/config>.
|
15
|
+
|
16
|
+
## Features
|
17
|
+
|
18
|
+
* simple YAML config files
|
19
|
+
* config files support ERB
|
20
|
+
* config files support inheritance and multiple environments
|
21
|
+
* access config information via convenient object member notation
|
22
|
+
* support for multi-level settings (`Settings.group.subgroup.setting`)
|
23
|
+
* local developer settings ignored when committing the code
|
24
|
+
|
25
|
+
## Compatibility
|
26
|
+
|
27
|
+
Current version supports and is [tested](.github/workflows/build.yml#L19)
|
28
|
+
for the following interpreters and frameworks:
|
29
|
+
|
30
|
+
* Interpreters
|
31
|
+
* [Ruby](https://www.ruby-lang.org) `>= 2.7`
|
32
|
+
* Application frameworks
|
33
|
+
* Rails `>= 6.0`
|
34
|
+
* Padrino
|
35
|
+
* Sinatra
|
36
|
+
|
37
|
+
## Installing
|
38
|
+
|
39
|
+
Add the gem to your `Gemfile` and run `bundle install` to install it:
|
40
|
+
|
41
|
+
```ruby
|
42
|
+
gem "confset", "~> 1.0.0"
|
43
|
+
```
|
44
|
+
|
45
|
+
You can also install by the GitHub packages server:
|
46
|
+
|
47
|
+
```ruby
|
48
|
+
source "https://rubygems.pkg.github.com/dcotecnologia" do
|
49
|
+
gem "confset", "1.0.0"
|
50
|
+
end
|
51
|
+
```
|
52
|
+
|
53
|
+
Or directly using the repository version:
|
54
|
+
|
55
|
+
```ruby
|
56
|
+
gem "confset", github: "dcotecnologia/confset", branch: "master"
|
57
|
+
```
|
58
|
+
|
59
|
+
### Installing on Rails
|
60
|
+
|
61
|
+
Then run
|
62
|
+
|
63
|
+
rails g confset:install
|
64
|
+
|
65
|
+
which will generate customizable config file `config/initializers/confset.rb` and set of default settings files:
|
66
|
+
|
67
|
+
config/settings.yml
|
68
|
+
config/settings.local.yml
|
69
|
+
config/settings/development.yml
|
70
|
+
config/settings/production.yml
|
71
|
+
config/settings/test.yml
|
72
|
+
|
73
|
+
You can now edit them to adjust to your needs.
|
74
|
+
|
75
|
+
### Installing on Padrino
|
76
|
+
|
77
|
+
Then edit `app.rb` and register `Confset`
|
78
|
+
|
79
|
+
```ruby
|
80
|
+
register Confset
|
81
|
+
```
|
82
|
+
|
83
|
+
### Installing on Sinatra
|
84
|
+
|
85
|
+
Afterwards in need to register `Confset` in your app and give it a root so
|
86
|
+
it can find the config files.
|
87
|
+
|
88
|
+
```ruby
|
89
|
+
set :root, File.dirname(__FILE__)
|
90
|
+
register Confset
|
91
|
+
```
|
92
|
+
|
93
|
+
### Installing on other ruby projects
|
94
|
+
|
95
|
+
Add the gem to your `Gemfile` and run `bundle install` to install it.
|
96
|
+
Then initialize `Confset` manually within your configure block.
|
97
|
+
|
98
|
+
```ruby
|
99
|
+
Confset.load_and_set_settings(Confset.setting_files("/path/to/config_root", "your_project_environment"))
|
100
|
+
```
|
101
|
+
|
102
|
+
It's also possible to initialize `Confset` manually within your configure block
|
103
|
+
if you want to just give it some yml paths to load from.
|
104
|
+
|
105
|
+
```ruby
|
106
|
+
Confset.load_and_set_settings("/path/to/yaml1", "/path/to/yaml2", ...)
|
107
|
+
```
|
108
|
+
|
109
|
+
## Accessing the Settings object
|
110
|
+
|
111
|
+
After installing the gem, `Settings` object will become available globally and
|
112
|
+
by default will be compiled from the files listed below. Settings defined in
|
113
|
+
files that are lower in the list override settings higher.
|
114
|
+
|
115
|
+
config/settings.yml
|
116
|
+
config/settings/#{environment}.yml
|
117
|
+
config/environments/#{environment}.yml
|
118
|
+
|
119
|
+
config/settings.local.yml
|
120
|
+
config/settings/#{environment}.local.yml
|
121
|
+
config/environments/#{environment}.local.yml
|
122
|
+
|
123
|
+
Entries can be accessed via object member notation:
|
124
|
+
|
125
|
+
```ruby
|
126
|
+
Settings.my_config_entry
|
127
|
+
```
|
128
|
+
|
129
|
+
Nested entries are supported:
|
130
|
+
|
131
|
+
```ruby
|
132
|
+
Settings.my_section.some_entry
|
133
|
+
```
|
134
|
+
|
135
|
+
Alternatively, you can also use the `[]` operator if you don't know which exact
|
136
|
+
setting you need to access ahead of time.
|
137
|
+
|
138
|
+
```ruby
|
139
|
+
# All the following are equivalent to Settings.my_section.some_entry
|
140
|
+
Settings.my_section[:some_entry]
|
141
|
+
Settings.my_section['some_entry']
|
142
|
+
Settings[:my_section][:some_entry]
|
143
|
+
```
|
144
|
+
|
145
|
+
### Reloading settings
|
146
|
+
|
147
|
+
You can reload the Settings object at any time by running `Settings.reload!`.
|
148
|
+
|
149
|
+
### Reloading settings and config files
|
150
|
+
|
151
|
+
You can also reload the `Settings` object from different config files at runtime.
|
152
|
+
|
153
|
+
For example, in your tests if you want to test the production settings, you can:
|
154
|
+
|
155
|
+
```ruby
|
156
|
+
Rails.env = "production"
|
157
|
+
Settings.reload_from_files(
|
158
|
+
Rails.root.join("config", "settings.yml").to_s,
|
159
|
+
Rails.root.join("config", "settings", "#{Rails.env}.yml").to_s,
|
160
|
+
Rails.root.join("config", "environments", "#{Rails.env}.yml").to_s
|
161
|
+
)
|
162
|
+
```
|
163
|
+
|
164
|
+
### Environment specific config files
|
165
|
+
|
166
|
+
You can have environment specific config files. Environment specific config
|
167
|
+
entries take precedence over common config entries.
|
168
|
+
|
169
|
+
Example development environment config file:
|
170
|
+
|
171
|
+
```ruby
|
172
|
+
#{Rails.root}/config/environments/development.yml
|
173
|
+
```
|
174
|
+
|
175
|
+
Example production environment config file:
|
176
|
+
|
177
|
+
```ruby
|
178
|
+
#{Rails.root}/config/environments/production.yml
|
179
|
+
```
|
180
|
+
|
181
|
+
### Developer specific config files
|
182
|
+
|
183
|
+
If you want to have local settings, specific to your machine or development
|
184
|
+
environment, you can use the following files, which are automatically `.gitignore` :
|
185
|
+
|
186
|
+
```ruby
|
187
|
+
Rails.root.join("config", "settings.local.yml").to_s,
|
188
|
+
Rails.root.join("config", "settings", "#{Rails.env}.local.yml").to_s,
|
189
|
+
Rails.root.join("config", "environments", "#{Rails.env}.local.yml").to_s
|
190
|
+
```
|
191
|
+
|
192
|
+
**NOTE:** The file `settings.local.yml` will not be loaded in tests to prevent
|
193
|
+
local configuration from causing flaky or non-deterministic tests.
|
194
|
+
Environment-specific files (e.g. `settings/test.local.yml`) will still be loaded
|
195
|
+
to allow test-specific credentials.
|
196
|
+
|
197
|
+
### Adding sources at runtime
|
198
|
+
|
199
|
+
You can add new YAML config files at runtime. Just use:
|
200
|
+
|
201
|
+
```ruby
|
202
|
+
Settings.add_source!("/path/to/source.yml")
|
203
|
+
Settings.reload!
|
204
|
+
```
|
205
|
+
|
206
|
+
This will use the given source.yml file and use its settings to overwrite any previous ones.
|
207
|
+
|
208
|
+
On the other hand, you can prepend a YML file to the list of configuration files:
|
209
|
+
|
210
|
+
```ruby
|
211
|
+
Settings.prepend_source!("/path/to/source.yml")
|
212
|
+
Settings.reload!
|
213
|
+
```
|
214
|
+
|
215
|
+
This will do the same as `add_source`, but the given YML file will be loaded
|
216
|
+
first (instead of last) and its settings will be overwritten by any other
|
217
|
+
configuration file. This is especially useful if you want to define defaults.
|
218
|
+
|
219
|
+
One thing I like to do for my Rails projects is provide a local.yml config file
|
220
|
+
that is .gitignored (so its independent per developer). Then I create a new
|
221
|
+
initializer in `config/initializers/add_local_confset.rb` with the contents
|
222
|
+
|
223
|
+
```ruby
|
224
|
+
Settings.add_source!("#{Rails.root}/config/settings/local.yml")
|
225
|
+
Settings.reload!
|
226
|
+
```
|
227
|
+
|
228
|
+
> Note: this is an example usage, it is easier to just use the default local
|
229
|
+
> files `settings.local.yml`, `settings/#{Rails.env}.local.yml` and
|
230
|
+
> `environments/#{Rails.env}.local.yml` for your developer specific settings.
|
231
|
+
|
232
|
+
You also have the option to add a raw hash as a source. One use case might be
|
233
|
+
storing settings in the database or in environment variables that overwrite what
|
234
|
+
is in the YML files.
|
235
|
+
|
236
|
+
```ruby
|
237
|
+
Settings.add_source!({some_secret: ENV['some_secret']})
|
238
|
+
Settings.reload!
|
239
|
+
```
|
240
|
+
|
241
|
+
You may pass a hash to `prepend_source!` as well.
|
242
|
+
|
243
|
+
## Embedded Ruby (ERB)
|
244
|
+
|
245
|
+
Embedded Ruby is allowed in the YAML configuration files. ERB will be evaluated
|
246
|
+
at load time by default, and when the `evaluate_erb_in_yaml` configuration
|
247
|
+
is set to `true`.
|
248
|
+
|
249
|
+
Consider the two following config files.
|
250
|
+
|
251
|
+
* ```#{Rails.root}/config/settings.yml```
|
252
|
+
|
253
|
+
```yaml
|
254
|
+
size: 1
|
255
|
+
server: google.com
|
256
|
+
```
|
257
|
+
|
258
|
+
* ```#{Rails.root}/config/environments/development.yml```
|
259
|
+
|
260
|
+
```yaml
|
261
|
+
size: 2
|
262
|
+
computed: <%= 1 + 2 + 3 %>
|
263
|
+
section:
|
264
|
+
size: 3
|
265
|
+
servers: [ {name: yahoo.com}, {name: amazon.com} ]
|
266
|
+
```
|
267
|
+
|
268
|
+
Notice that the environment specific config entries overwrite the common entries.
|
269
|
+
|
270
|
+
```ruby
|
271
|
+
Settings.size # => 2
|
272
|
+
Settings.server # => google.com
|
273
|
+
```
|
274
|
+
|
275
|
+
Notice the embedded Ruby.
|
276
|
+
|
277
|
+
```ruby
|
278
|
+
Settings.computed # => 6
|
279
|
+
```
|
280
|
+
|
281
|
+
Notice that object member notation is maintained even in nested entries.
|
282
|
+
|
283
|
+
```ruby
|
284
|
+
Settings.section.size # => 3
|
285
|
+
```
|
286
|
+
|
287
|
+
Notice array notation and object member notation is maintained.
|
288
|
+
|
289
|
+
```ruby
|
290
|
+
Settings.section.servers[0].name # => yahoo.com
|
291
|
+
Settings.section.servers[1].name # => amazon.com
|
292
|
+
```
|
293
|
+
|
294
|
+
## Configuration
|
295
|
+
|
296
|
+
There are multiple configuration options available, however you can customize
|
297
|
+
`Confset` only once, preferably during application initialization phase:
|
298
|
+
|
299
|
+
```ruby
|
300
|
+
Confset.setup do |config|
|
301
|
+
config.const_name = 'Settings'
|
302
|
+
# ...
|
303
|
+
end
|
304
|
+
```
|
305
|
+
|
306
|
+
After installing `Confset` in Rails, you will find automatically generated file
|
307
|
+
that contains default configuration located at `config/initializers/confset.rb`.
|
308
|
+
|
309
|
+
### General
|
310
|
+
|
311
|
+
* `const_name` - name of the object holing you settings. Default: `'Settings'`
|
312
|
+
* `evaluate_erb_in_yaml` - evaluate ERB in YAML config files. Set to false if
|
313
|
+
the config file contains ERB that should not be evaluated at load time. Default: `true`
|
314
|
+
|
315
|
+
### Merge customization
|
316
|
+
|
317
|
+
* `overwrite_arrays` - overwrite arrays found in previously loaded settings file.
|
318
|
+
Default: `true`
|
319
|
+
* `merge_hash_arrays` - merge hashes inside of arrays from previously loaded
|
320
|
+
settings files. Makes sense only when `overwrite_arrays = false`. Default: `false`
|
321
|
+
* `knockout_prefix` - ability to remove elements of the array set in earlier
|
322
|
+
loaded settings file. Makes sense only when `overwrite_arrays = false`, otherwise
|
323
|
+
array settings would be overwritten by default. Default: `nil`
|
324
|
+
* `merge_nil_values` - `nil` values will overwrite an existing value when
|
325
|
+
merging configs. Default: `true`.
|
326
|
+
|
327
|
+
```ruby
|
328
|
+
# merge_nil_values is true by default
|
329
|
+
c = Confset.load_files("./spec/fixtures/development.yml") # => #<Confset::Options size=2, ...>
|
330
|
+
c.size # => 2
|
331
|
+
c.merge!(size: nil) => #<Confset::Options size=nil, ...>
|
332
|
+
c.size # => nil
|
333
|
+
```
|
334
|
+
|
335
|
+
```ruby
|
336
|
+
# To reject nil values when merging settings:
|
337
|
+
Confset.setup do |config|
|
338
|
+
config.merge_nil_values = false
|
339
|
+
end
|
340
|
+
|
341
|
+
c = Confset.load_files("./spec/fixtures/development.yml") # => #<Confset::Options size=2, ...>
|
342
|
+
c.size # => 2
|
343
|
+
c.merge!(size: nil) => #<Confset::Options size=nil, ...>
|
344
|
+
c.size # => 2
|
345
|
+
```
|
346
|
+
|
347
|
+
Check [Deep Merge](https://github.com/danielsdeleo/deep_merge) for more details.
|
348
|
+
|
349
|
+
### Validation
|
350
|
+
|
351
|
+
With Ruby 2.1 or newer, you can optionally define a [schema](https://github.com/dry-rb/dry-schema)
|
352
|
+
or [contract](https://github.com/dry-rb/dry-validation) (added in `config-2.1`)
|
353
|
+
using [dry-rb](https://github.com/dry-rb) to validate presence (and type) of
|
354
|
+
specific config values. Generally speaking contracts allow to describe more
|
355
|
+
complex validations with depencecies between fields.
|
356
|
+
|
357
|
+
If you provide either validation option (or both) it will
|
358
|
+
automatically be used to validate your config. If validation fails it will
|
359
|
+
raise a `Confset::Validation::Error` containing information about all
|
360
|
+
the mismatches between the schema and your config.
|
361
|
+
|
362
|
+
Both examples below demonstrates how to ensure that the configuration
|
363
|
+
has an optional `email` and the `youtube` structure with the `api_key` field filled.
|
364
|
+
The contract adds an additional rule.
|
365
|
+
|
366
|
+
#### Contract
|
367
|
+
|
368
|
+
Leverage dry-validation, you can create a contract with a params schema and rules:
|
369
|
+
|
370
|
+
```ruby
|
371
|
+
class ConfigContract < Dry::Validation::Contract
|
372
|
+
params do
|
373
|
+
optional(:email).maybe(:str?)
|
374
|
+
|
375
|
+
required(:youtube).schema do
|
376
|
+
required(:api_key).filled
|
377
|
+
end
|
378
|
+
end
|
379
|
+
|
380
|
+
rule(:email) do
|
381
|
+
unless /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i.match?(value)
|
382
|
+
key.failure('has invalid format')
|
383
|
+
end
|
384
|
+
end
|
385
|
+
end
|
386
|
+
|
387
|
+
Confset.setup do |config|
|
388
|
+
config.validation_contract = ConfigContract.new
|
389
|
+
end
|
390
|
+
```
|
391
|
+
|
392
|
+
The above example adds a rule to ensure the `email` is valid by matching
|
393
|
+
it against the provided regular expression.
|
394
|
+
|
395
|
+
Check [dry-validation](https://github.com/dry-rb/dry-validation) for more details.
|
396
|
+
|
397
|
+
#### Schema
|
398
|
+
|
399
|
+
You may also specify a schema using [dry-schema](https://github.com/dry-rb/dry-schema):
|
400
|
+
|
401
|
+
```ruby
|
402
|
+
Confset.setup do |config|
|
403
|
+
# ...
|
404
|
+
config.schema do
|
405
|
+
optional(:email).maybe(:str?)
|
406
|
+
|
407
|
+
required(:youtube).schema do
|
408
|
+
required(:api_key).filled
|
409
|
+
end
|
410
|
+
end
|
411
|
+
end
|
412
|
+
```
|
413
|
+
|
414
|
+
Check [dry-schema](https://github.com/dry-rb/dry-schema) for more details.
|
415
|
+
|
416
|
+
### Missing keys
|
417
|
+
|
418
|
+
For an example settings file:
|
419
|
+
|
420
|
+
```yaml
|
421
|
+
size: 1
|
422
|
+
server: google.com
|
423
|
+
```
|
424
|
+
|
425
|
+
You can test if a value was set for a given key using `key?` and its alias `has_key?`:
|
426
|
+
|
427
|
+
```ruby
|
428
|
+
Settings.key?(:path)
|
429
|
+
# => false
|
430
|
+
Settings.key?(:server)
|
431
|
+
# => true
|
432
|
+
```
|
433
|
+
|
434
|
+
By default, accessing to a missing key returns `nil`:
|
435
|
+
|
436
|
+
```ruby
|
437
|
+
Settings.key?(:path)
|
438
|
+
# => false
|
439
|
+
Settings.path
|
440
|
+
# => nil
|
441
|
+
```
|
442
|
+
|
443
|
+
This is not "typo-safe". To solve this problem, you can configure
|
444
|
+
the `fail_on_missing` option:
|
445
|
+
|
446
|
+
```ruby
|
447
|
+
Confset.setup do |config|
|
448
|
+
config.fail_on_missing = true
|
449
|
+
# ...
|
450
|
+
end
|
451
|
+
```
|
452
|
+
|
453
|
+
So it will raise a `KeyError` when accessing a non-existing key
|
454
|
+
(similar to `Hash#fetch` behaviour):
|
455
|
+
|
456
|
+
```ruby
|
457
|
+
Settings.path
|
458
|
+
# => raises KeyError: key not found: :path
|
459
|
+
```
|
460
|
+
|
461
|
+
### Environment variables
|
462
|
+
|
463
|
+
See section below for more details.
|
464
|
+
|
465
|
+
## Working with environment variables
|
466
|
+
|
467
|
+
To load environment variables from the `ENV` object, that will override any settings
|
468
|
+
defined in files, set the `use_env` to true in your
|
469
|
+
`config/initializers/confset.rb` file:
|
470
|
+
|
471
|
+
```ruby
|
472
|
+
Confset.setup do |config|
|
473
|
+
config.const_name = 'Settings'
|
474
|
+
config.use_env = true
|
475
|
+
end
|
476
|
+
```
|
477
|
+
|
478
|
+
Now config would read values from the ENV object to the settings. For the
|
479
|
+
example above it would look for keys starting with `Settings`:
|
480
|
+
|
481
|
+
```ruby
|
482
|
+
ENV['Settings.section.size'] = 1
|
483
|
+
ENV['Settings.section.server'] = 'google.com'
|
484
|
+
```
|
485
|
+
|
486
|
+
It won't work with arrays, though.
|
487
|
+
|
488
|
+
It is considered an error to use environment variables to simutaneously assign
|
489
|
+
a "flat" value and a multi-level value to a key.
|
490
|
+
|
491
|
+
```ruby
|
492
|
+
# Raises an error when settings are loaded
|
493
|
+
ENV['BACKEND_DATABASE'] = 'development'
|
494
|
+
ENV['BACKEND_DATABASE_USER'] = 'postgres'
|
495
|
+
```
|
496
|
+
|
497
|
+
Instead, specify keys of equal depth in the environment variable names:
|
498
|
+
|
499
|
+
```ruby
|
500
|
+
ENV['BACKEND_DATABASE_NAME'] = 'development'
|
501
|
+
ENV['BACKEND_DATABASE_USER'] = 'postgres'
|
502
|
+
```
|
503
|
+
|
504
|
+
### Working with Heroku
|
505
|
+
|
506
|
+
Heroku uses ENV object to store sensitive settings.
|
507
|
+
You cannot upload such files to Heroku because it's ephemeral filesystem gets
|
508
|
+
recreated from the git sources on each instance refresh. To use config with Heroku
|
509
|
+
just set the `use_env` var to `true` as mentioned above.
|
510
|
+
|
511
|
+
To upload your local values to Heroku you could ran `bundle exec rake config:heroku`.
|
512
|
+
|
513
|
+
### Fine-tuning
|
514
|
+
|
515
|
+
You can customize how environment variables are processed:
|
516
|
+
|
517
|
+
* `env_prefix` (default: `const_name`) - load only ENV variables starting with
|
518
|
+
this prefix (case-sensitive)
|
519
|
+
* `env_separator` (default: `'.'`) - what string to use as level separator -
|
520
|
+
default value of `.` works well with Heroku, but you might want to change it
|
521
|
+
for example for `__` to easy override settings from command line, where using dots
|
522
|
+
in variable names might not be allowed (eg. Bash)
|
523
|
+
* `env_converter` (default: `:downcase`) - how to process variables names:
|
524
|
+
* `nil` - no change
|
525
|
+
* `:downcase` - convert to lower case
|
526
|
+
* `env_parse_values` (default: `true`) - try to parse values to a correct type (`Boolean`, `Integer`, `Float`, `String`)
|
527
|
+
|
528
|
+
For instance, given the following environment:
|
529
|
+
|
530
|
+
```bash
|
531
|
+
SETTINGS__SECTION__SERVER_SIZE=1
|
532
|
+
SETTINGS__SECTION__SERVER=google.com
|
533
|
+
SETTINGS__SECTION__SSL_ENABLED=false
|
534
|
+
```
|
535
|
+
|
536
|
+
And the following configuration:
|
537
|
+
|
538
|
+
```ruby
|
539
|
+
Confset.setup do |config|
|
540
|
+
config.use_env = true
|
541
|
+
config.env_prefix = 'SETTINGS'
|
542
|
+
config.env_separator = '__'
|
543
|
+
config.env_converter = :downcase
|
544
|
+
config.env_parse_values = true
|
545
|
+
end
|
546
|
+
```
|
547
|
+
|
548
|
+
The following settings will be available:
|
549
|
+
|
550
|
+
```ruby
|
551
|
+
Settings.section.server_size # => 1
|
552
|
+
Settings.section.server # => 'google.com'
|
553
|
+
Settings.section.ssl_enabled # => false
|
554
|
+
```
|
555
|
+
|
556
|
+
### Working with AWS Secrets Manager
|
557
|
+
|
558
|
+
It is possible to parse variables stored in an AWS Secrets Manager Secret as if
|
559
|
+
they were environment variables by using `Confset::Sources::EnvSource`.
|
560
|
+
|
561
|
+
For example, the plaintext secret might look like this:
|
562
|
+
|
563
|
+
```json
|
564
|
+
{
|
565
|
+
"Settings.foo": "hello",
|
566
|
+
"Settings.bar": "world",
|
567
|
+
}
|
568
|
+
```
|
569
|
+
|
570
|
+
In order to load those settings, fetch the settings from AWS Secrets Manager,
|
571
|
+
parse the plaintext as JSON, pass the resulting `Hash` into a new `EnvSource`,
|
572
|
+
load the new source, and reload.
|
573
|
+
|
574
|
+
```ruby
|
575
|
+
# fetch secrets from AWS
|
576
|
+
client = Aws::SecretsManager::Client.new
|
577
|
+
response = client.get_secret_value(secret_id: "#{ENV['ENVIRONMENT']}/my_application")
|
578
|
+
secrets = JSON.parse(response.secret_string)
|
579
|
+
|
580
|
+
# load secrets into config
|
581
|
+
secret_source = Confset::Sources::EnvSource.new(secrets)
|
582
|
+
Settings.add_source!(secret_source)
|
583
|
+
Settings.reload!
|
584
|
+
```
|
585
|
+
|
586
|
+
In this case, the following settings will be available:
|
587
|
+
|
588
|
+
```ruby
|
589
|
+
Settings.foo # => "hello"
|
590
|
+
Settings.bar # => "world"
|
591
|
+
```
|
592
|
+
|
593
|
+
By default, `EnvSource` will use configuration for `env_prefix`, `env_separator`,
|
594
|
+
`env_converter`, and `env_parse_values`, but any of these can be overridden in
|
595
|
+
the constructor.
|
596
|
+
|
597
|
+
```ruby
|
598
|
+
secret_source = Confset::Sources::EnvSource.new(secrets,
|
599
|
+
prefix: 'MyConfig',
|
600
|
+
separator: '__',
|
601
|
+
converter: nil,
|
602
|
+
parse_values: false)
|
603
|
+
```
|
604
|
+
|
605
|
+
## Contributing
|
606
|
+
|
607
|
+
Any and all contributions offered in any form, past present or future are
|
608
|
+
understood to be in complete agreement and acceptance with [MIT](LICENSE) license.
|
609
|
+
|
610
|
+
### Running specs
|
611
|
+
|
612
|
+
Setup
|
613
|
+
|
614
|
+
```sh
|
615
|
+
bundle install
|
616
|
+
```
|
617
|
+
|
618
|
+
Run lint:
|
619
|
+
|
620
|
+
```sh
|
621
|
+
bundle exec rubocop --parallel
|
622
|
+
```
|
623
|
+
|
624
|
+
Run specs:
|
625
|
+
|
626
|
+
```sh
|
627
|
+
bundle exec rspec
|
628
|
+
```
|
629
|
+
|
630
|
+
## Authors
|
631
|
+
|
632
|
+
* [Danilo Carolino](@danilogco) - [DCO Tecnologia](https://github.com/dcotecnologia)
|
633
|
+
|
634
|
+
## Contributors
|
635
|
+
|
636
|
+
* [Piotr Kuczynski](@pkuczynski) - original config gem project
|
637
|
+
* [Fred Wu](@fredwu) - original config gem project
|
638
|
+
* [Jacques Crocker](@railsjedi) - original config gem project
|
639
|
+
* Inherited from [AppConfig](https://github.com/cjbottaro/app_config) by
|
640
|
+
[Christopher J. Bottaro](@cjbottaro)
|
641
|
+
|
642
|
+
### Code Contributors
|
643
|
+
|
644
|
+
Any and all contributions offered in any form, past present or future are
|
645
|
+
understood to be in complete agreement and acceptance with the [MIT](LICENSE) license.
|
646
|
+
|
647
|
+
## License
|
648
|
+
|
649
|
+
Copyright (c) 2022 DCO Tecnologia. Released under the [MIT License](LICENSE.md).
|
data/lib/confset/options.rb
CHANGED
@@ -42,16 +42,18 @@ module Confset
|
|
42
42
|
end
|
43
43
|
}
|
44
44
|
|
45
|
-
|
46
|
-
h[key] ||= {}
|
47
|
-
}
|
45
|
+
begin
|
46
|
+
leaf = keys[0...-1].inject(hash) { |h, key| h[key] ||= {} }
|
48
47
|
|
49
|
-
|
50
|
-
|
51
|
-
|
48
|
+
if leaf.is_a?(Hash)
|
49
|
+
leaf[keys.last] = parse_values ? __value(value) : value
|
50
|
+
else
|
51
|
+
conflicting_key = (prefix + keys[0...-1]).join(separator)
|
52
|
+
Confset.logger.error("Environment variable #{variable} conflicts with variable #{conflicting_key}")
|
53
|
+
end
|
54
|
+
rescue IndexError
|
55
|
+
Confset.logger.warn("Wasn't possible to parse the env variable: #{variable}")
|
52
56
|
end
|
53
|
-
|
54
|
-
leaf[keys.last] = parse_values ? __value(value) : value
|
55
57
|
end
|
56
58
|
|
57
59
|
hash
|
data/lib/confset/version.rb
CHANGED
data/lib/confset.rb
CHANGED
@@ -29,6 +29,20 @@ module Confset
|
|
29
29
|
evaluate_erb_in_yaml: true
|
30
30
|
)
|
31
31
|
|
32
|
+
# Log information about the library.
|
33
|
+
# Confset.logger.info("some info")
|
34
|
+
# Documentation: https://ruby-doc.org/stdlib-3.1.2/libdoc/logger/rdoc/Logger.html
|
35
|
+
class << self
|
36
|
+
attr_writer :logger
|
37
|
+
|
38
|
+
def logger
|
39
|
+
@logger ||= Logger.new($stdout).tap do |log|
|
40
|
+
log.progname = self.name
|
41
|
+
end
|
42
|
+
end
|
43
|
+
end
|
44
|
+
|
45
|
+
|
32
46
|
def self.setup
|
33
47
|
yield self unless @_ran_once
|
34
48
|
@_ran_once = true
|
data/spec/config_env_spec.rb
CHANGED
@@ -216,17 +216,6 @@ describe Confset::Options do
|
|
216
216
|
expect(config.new_var).to eq("value")
|
217
217
|
end
|
218
218
|
|
219
|
-
context "and env variable names conflict with new namespaces" do
|
220
|
-
it "should throw a descriptive error message" do
|
221
|
-
ENV["Settings.backend_database"] = "development"
|
222
|
-
ENV["Settings.backend_database.user"] = "postgres"
|
223
|
-
|
224
|
-
expected_message = "Environment variable Settings.backend_database.user "\
|
225
|
-
"conflicts with variable Settings.backend_database"
|
226
|
-
expect { config }.to raise_error(RuntimeError, expected_message)
|
227
|
-
end
|
228
|
-
end
|
229
|
-
|
230
219
|
context "and env variable names conflict with existing namespaces" do
|
231
220
|
it "should allow overriding the namespace" do
|
232
221
|
ENV["Settings.databases"] = "new databases"
|
data/spec/spec_helper.rb
CHANGED
metadata
CHANGED
@@ -1,17 +1,17 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: confset
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 1.0.
|
4
|
+
version: 1.0.1
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Danilo Carolino
|
8
8
|
- Piotr Kuczynski
|
9
9
|
- Fred Wu
|
10
10
|
- Jacques Crocker
|
11
|
-
autorequire:
|
11
|
+
autorequire:
|
12
12
|
bindir: bin
|
13
13
|
cert_chain: []
|
14
|
-
date: 2022-05-
|
14
|
+
date: 2022-05-30 00:00:00.000000000 Z
|
15
15
|
dependencies:
|
16
16
|
- !ruby/object:Gem::Dependency
|
17
17
|
name: deep_merge
|
@@ -115,6 +115,20 @@ dependencies:
|
|
115
115
|
- - "~>"
|
116
116
|
- !ruby/object:Gem::Version
|
117
117
|
version: '0.11'
|
118
|
+
- !ruby/object:Gem::Dependency
|
119
|
+
name: pry
|
120
|
+
requirement: !ruby/object:Gem::Requirement
|
121
|
+
requirements:
|
122
|
+
- - "~>"
|
123
|
+
- !ruby/object:Gem::Version
|
124
|
+
version: '0.14'
|
125
|
+
type: :development
|
126
|
+
prerelease: false
|
127
|
+
version_requirements: !ruby/object:Gem::Requirement
|
128
|
+
requirements:
|
129
|
+
- - "~>"
|
130
|
+
- !ruby/object:Gem::Version
|
131
|
+
version: '0.14'
|
118
132
|
- !ruby/object:Gem::Dependency
|
119
133
|
name: rubocop
|
120
134
|
requirement: !ruby/object:Gem::Requirement
|
@@ -165,9 +179,10 @@ executables: []
|
|
165
179
|
extensions: []
|
166
180
|
extra_rdoc_files: []
|
167
181
|
files:
|
182
|
+
- CHANGELOG.md
|
183
|
+
- LICENSE.md
|
184
|
+
- README.md
|
168
185
|
- Rakefile
|
169
|
-
- docs/CHANGELOG.md
|
170
|
-
- docs/LICENSE.md
|
171
186
|
- lib/confset.rb
|
172
187
|
- lib/confset/configuration.rb
|
173
188
|
- lib/confset/integrations/heroku.rb
|
@@ -233,7 +248,7 @@ homepage: https://github.com/dcotecnologia/confset
|
|
233
248
|
licenses:
|
234
249
|
- MIT
|
235
250
|
metadata: {}
|
236
|
-
post_install_message:
|
251
|
+
post_install_message:
|
237
252
|
rdoc_options:
|
238
253
|
- "--charset=UTF-8"
|
239
254
|
require_paths:
|
@@ -250,7 +265,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
250
265
|
version: '0'
|
251
266
|
requirements: []
|
252
267
|
rubygems_version: 3.3.7
|
253
|
-
signing_key:
|
268
|
+
signing_key:
|
254
269
|
specification_version: 4
|
255
270
|
summary: Effortless multi-environment settings in Rails, Sinatra, Pandrino and others
|
256
271
|
test_files:
|