global 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b01380c2ead8dd05766d2d01dff1fbc24aff74ab22d6cdca72b6d5bcf92409e8
-  data.tar.gz: 596fd34a00183fca92f01cab9e6a0214275036abc93accea2f88f4646a764448
+  metadata.gz: d82e24b3a7c94f65e370d1b16142e028d3acf1ce3fe8064e9e9fcb9e4683d46e
+  data.tar.gz: 809e1b6ac4e2f0ada443202b1d80ec7d663488515f682079cd07bc02335983c4
 SHA512:
-  metadata.gz: 6fa1a2e2ebc3092e3b61a4c2ce7104db18947c1fb1a9a73b5cfe2bceecfb575485c9cf426a841f63f72b08db84cee51d0fec3eb7d4f4db629d3d9b3edde13252
-  data.tar.gz: fee130c0b00643657da8f8bc191a86c111e80a8da40ac1b62c0d34765d775e70ac7393078213425987af1378bcaac02a8f245dc66804aa4b094a2f1f393653fb
+  metadata.gz: b290b4951da9d199d64ec8a27bdf630be5691ec1af0829d31e01872c1260893e2a3626fcc55a70f9ac816192279fbf04a4a2823dd770127808bd63b62ad8016d
+  data.tar.gz: afa4586a51919a0d483dbcd01e5fd027cd6a79aebaea070c544c53f4838ccbbece9312536d40ed475adf1cc207ef7864937639baa60de7bab1918de3a081944a

data/.rubocop.yml

@@ -1,3 +1,7 @@
+Metrics/MethodLength:
+  Enabled: true
+  Max: 11
+
 Layout/EmptyLinesAroundBlockBody:
   Enabled: false
 
@@ -29,10 +33,16 @@ Layout/MultilineMethodCallIndentation:
   Enabled: true
   EnforcedStyle: indented
 
-Layout/AlignHash:
+Layout/HashAlignment:
   Enabled: true
   EnforcedLastArgumentHashStyle: always_ignore
 
+Lint/RaiseException:
+  Enabled: true
+
+Lint/StructNewOverride:
+  Enabled: true
+
 Style/RaiseArgs:
   EnforcedStyle: compact
 
@@ -43,12 +53,21 @@ Style/FrozenStringLiteralComment:
   Enabled: true
   EnforcedStyle: always
 
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true
+
 Style/RegexpLiteral:
   Enabled: true
   EnforcedStyle: slashes
   AllowInnerSlashes: false
 
-Layout/IndentHash:
+Layout/FirstHashElementIndentation:
   EnforcedStyle: consistent
 
 Style/Documentation:
@@ -56,36 +75,36 @@ Style/Documentation:
 
 Style/SafeNavigation:
   Enabled: true
-  Whitelist:
+  AllowedMethods:
     - present?
     - blank?
     - presence
 
 Lint/AmbiguousBlockAssociation:
   Exclude:
-    - 'spec/**/*'
+    - "spec/**/*"
 
 Naming/PredicateName:
   Exclude:
-    - 'spec/**/*'
+    - "spec/**/*"
 
 Style/NumericPredicate:
   Exclude:
-    - 'spec/**/*'
+    - "spec/**/*"
 
 Metrics/BlockLength:
   Exclude:
-    - 'spec/**/*'
+    - "spec/**/*"
 
-Metrics/LineLength:
+Layout/LineLength:
   Max: 120
   Exclude:
-    - 'spec/**/*'
+    - "spec/**/*"
 
 Metrics/AbcSize:
   Max: 22
   Exclude:
-    - 'spec/**/*'
+    - "spec/**/*"
 
 Style/ModuleFunction:
   EnforcedStyle: extend_self

data/.ruby-version

@@ -1 +1 @@
-2.5.1
+2.6.6

data/.travis.yml

@@ -1,27 +1,21 @@
 language: ruby
+os: linux
+dist: bionic
 
 cache:
   bundler: true
 
 rvm:
-  - 2.2
-  - 2.3
   - 2.4
   - 2.5
-  - jruby-19mode
+  - 2.6
+  - 2.7
   - ruby-head
   - jruby-head
 
 notifications:
   email: false
 
-sudo: false
-
-branches:
-  only:
-    - master
-    - development
-
 matrix:
   allow_failures:
     - rvm: ruby-head

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at leopard.not.a@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

data/README.md

@@ -1,6 +1,8 @@
 # Global [![Build Status](https://travis-ci.org/railsware/global.png)](https://travis-ci.org/railsware/global) [![Code Climate](https://codeclimate.com/github/railsware/global.png)](https://codeclimate.com/github/railsware/global)
 
-The 'global' gem provides accessor methods for your configuration data and share configuration across backend and frontend. The data is stored in yaml files.
+The 'global' gem provides accessor methods for your configuration data and share configuration across backend and frontend.
+
+The data can be stored in [YAML](https://yaml.org) files on disk, or in the [AWS SSM Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html).
 
 ## Installation
 
@@ -10,41 +12,73 @@ Add to Gemfile:
 gem 'global'
 ```
 
+Refer to the documentation on your chosen backend class for other dependencies.
+
 ## Configuration
 
+Refer to the documentation on your chosen backend class for configuration options.
+
 ```ruby
-> Global.environment = "YOUR_ENV_HERE"
-> Global.config_directory = "PATH_TO_DIRECTORY_WITH_FILES"
-> Global.yaml_whitelist_classes = [] # optional configuration
+> Global.backend(:filesystem, environment: "YOUR_ENV_HERE", directory: "PATH_TO_DIRECTORY_WITH_FILES")
 ```
 
 Or you can use `configure` block:
 
 ```ruby
 Global.configure do |config|
-  config.environment = "YOUR_ENV_HERE"
-  config.config_directory = "PATH_TO_DIRECTORY_WITH_FILES"
-  config.yaml_whitelist_classes = [] # optional configuration
+  config.backend :filesystem, environment: "YOUR_ENV_HERE", directory: "PATH_TO_DIRECTORY_WITH_FILES"
+  # set up multiple backends and have them merged together:
+  config.backend :aws_parameter_store, prefix: '/prod/MyApp/'
+  config.backend :gcp_secret_manager, prefix: 'prod-myapp-', project_id: 'example'
 end
 ```
 
-For rails put initialization into `config/initializers/global.rb`
+### Using multiple backends
+
+Sometimes it is practical to store some configuration data on disk (and perhaps, commit it to source control), but
+keep some other data in a secure remote location. Which is why you can use more than one backend with Global.
+
+You can declare as many backends as you want; the configuration trees from the backends are deep-merged together,
+so that the backend declared later overwrites specific keys in the backend declared prior:
 
 ```ruby
 Global.configure do |config|
-  config.environment = Rails.env.to_s
-  config.config_directory = Rails.root.join('config/global').to_s
-  config.yaml_whitelist_classes = [] # optional configuration
+  config.backend :foo # loads tree { credentials: { hostname: 'api.com', username: 'dev', password: 'dev' } }
+  config.backend :bar # loads tree { credentials: { username: 'xxx', password: 'yyy' } }
 end
+
+Global.credentials.hostname # => 'api.com'
+Global.credentials.username # => 'xxx'
+Global.credentials.password # => 'yyy'
 ```
 
+For Rails, put initialization into `config/initializers/global.rb`.
+
+There are some sensible defaults, check your backend class for documentation.
+
+```ruby
+Global.configure do |config|
+  config.backend :filesystem
+end
+```
+
+### Filesystem storage
+
 The `yaml_whitelist_classes` configuration allows you to deserialize other classes from your `.yml`
 
+### AWS Parameter Store
+
+The `aws_options` configuration allows you to customize the AWS credentials and connection.
+
+### Google Cloud Secret Manager
+
+The `gcp_options` configuration allows you to customize the Google Cloud credentials and timeout.
+
 ## Usage
 
-### General
+### Filesystem
 
-Config file `config/global/hosts.yml`:
+For file `config/global/hosts.yml`:
 
 ```yml
 test:
@@ -84,9 +118,11 @@ Global.validations.regexp.email === 'mail@example.com'
 => true
 ```
 
-### Namespacing
+#### Per-environment sections
+
+You can define environment sections at the top level of every individual YAML file
 
-Config file `config/global/web/basic_auth.yml` with:
+For example, having a config file `config/global/web/basic_auth.yml` with:
 
 ```yml
 test:
@@ -100,7 +136,7 @@ production:
   password: supersecret
 ```
 
-After that in development environment we have:
+You get the correct configuration in development
 
 ```ruby
 > Global.web.basic_auth
@@ -109,7 +145,7 @@ After that in development environment we have:
 => "development_user"
 ```
 
-### Default section
+#### Default section
 
 Config file example:
 
@@ -124,9 +160,10 @@ production:
 
 Data from the default section is used until it's overridden in a specific environment.
 
-### Nested configurations
+#### Nested configurations
 
 Config file `global/nested.yml` with:
+
 ```yml
 test:
   group:
@@ -146,7 +183,7 @@ Nested options can then be accessed as follows:
 => "development value"
 ```
 
-### Environment files
+#### Environment files
 
 Config file `global/aws.yml` with:
 ```yml
@@ -180,7 +217,7 @@ Provide such configuration on `Global.environment = 'production'` environment:
 
 **Warning**: files with dot(s) in name will be skipped by Global (except this env files).
 
-### ERB support
+#### ERB support
 
 Config file `global/file_name.yml` with:
 
@@ -200,79 +237,185 @@ As a result, in the development environment we have:
 => 4
 ```
 
-### Reload configuration data
+### AWS Parameter Store
+
+Parameter Store is a secure configuration storage with at-rest encryption. Access is controlled through AWS IAM. You do not need to be hosted on AWS to use Parameter Store.
+
+Refer to the [official documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) to set up the store.
+
+Some steps you will need to follow:
+
+- Allocate an AWS IAM role for your app.
+- Create an IAM user for the role and pass credentials in standard AWS env vars (applications on Fargate get roles automatically).
+- Choose a prefix for the parameters. By default, the prefix is `/environment_name/AppClassName/`. You can change it with backend parameters (prefer to use '/' as separator).
+- Allow the role to read parameters from AWS SSM. Scope access by the prefix that you're going to use.
+- If you will use encrypted parameters: create a KMS key and allow the role to decrypt using the key.
+- Create parameters in Parameter Store. Use encryption for sensitive data like private keys and API credentials.
+
+#### Configuration examples
+
+Backend setup:
 
 ```ruby
-> Global.reload!
+# in config/environments/development.rb
+# you don't need to go to Parameter Store for dev machines
+Global.backend(:filesystem)
+
+# in config/environments/production.rb
+# enterprise grade protection for your secrets
+Global.backend(:aws_parameter_store, app_name: 'my_big_app')
 ```
 
-## JavaScript in Rails support
+Create parameters:
 
-### Configuration
+```
+/production/my_big_app/basic_auth/username => "bill"
+/production/my_big_app/basic_auth/password => "secret" # make sure to encrypt this one!
+/production/my_big_app/api_endpoint => "https://api.myapp.com"
+```
+
+Get configuration in the app:
 
 ```ruby
-Global.configure do |config|
-  config.namespace = "JAVASCRIPT_OBJECT_NAME" # default Global
-  config.except = ["LIST_OF_FILES_TO_EXCLUDE_ON_FRONT_END"] # default :all
-  config.only = ["LIST_OF_FILES_TO_INCLUDE_ON_FRONT_END"] # default []
-end
+# Encrypted parameters are automatically decrypted:
+> Global.basic_auth.password
+=> "secret"
+> Global.api_endpoint
+=> "https://api.myapp.com"
 ```
-By default all files are excluded due to security reasons. Don't include files which contain protected information like api keys or credentials.
 
-Require global file in `application.js`:
+### Google Cloud Secret Manager
 
-``` js
-/*
-= require global-js
-*/
-```
+Google Cloud Secret Manager allows you to store, manage, and access secrets as binary blobs or text strings. With the appropriate permissions, you can view the contents of the secret.
+Google Cloud Secret Manager works well for storing configuration information such as database passwords, API keys, or TLS certificates needed by an application at runtime.
+
+Refer to the [official documentation](https://cloud.google.com/secret-manager/docs) to set up the secret manager.
+
+Some steps you will need to follow:
 
-### Advanced Configuration
+- Choose a prefix for the secret key name. By default, the prefix is `environment_name-AppClassName-`. You can change it with backend parameters (prefer to use '-' as separator).
 
-In case you need different configurations for different parts of your application, you should create the files manually.
+#### Configuration examples
 
-If your application has `admin` and `application` namespace:
+Backend setup:
 
-```erb
-# app/assets/javascripts/admin/global.js.erb
-<%= Global.generate_js(namespace: "AdminSettings", only: %w(admin hosts)) %>
+```ruby
+# in config/environments/development.rb
+# you don't need to go to Parameter Store for dev machines
+Global.backend(:filesystem)
 
-# app/assets/javascripts/admin.js.coffee
-#= require admin/global
+# in config/environments/production.rb
+# enterprise grade protection for your secrets
+Global.backend(:gcp_secret_manager, prefix: 'prod-myapp-', project_id: 'example')
 ```
 
-```erb
-# app/assets/javascripts/application/global.js.erb
-<%= Global.generate_js(namespace: "AppSettings", except: %w(admin credentials)) %>
+Create secrets:
 
-# app/assets/javascripts/application.js.coffee
-#= require application/global
+```
+prod-myapp-basic_auth-username => "bill"
+prod-myapp-basic_auth-password => "secret"
+prod-myapp-api_endpoint => "https://api.myapp.com"
 ```
 
-### Usage
+Get configuration in the app:
 
-Config file example `global/hosts.yml`:
+```ruby
+# Encrypted parameters are automatically decrypted:
+> Global.basic_auth.password
+=> "secret"
+> Global.api_endpoint
+=> "https://api.myapp.com"
+```
 
-```yml
-development:
-  web: localhost
-  api: api.localhost
-production:
-  web: myhost.com
-  api: api.myhost.com
+### Reload configuration data
+
+```ruby
+> Global.reload!
 ```
-After that in development environment we have:
 
-``` js
-Global.hosts.web
-=> "localhost"
+## Using YAML configuration files with Rails Webpacker
+
+If you use the `:filesystem` backend, you can reuse the same configuration files on the frontend:
+
+Add [js-yaml](https://www.npmjs.com/package/js-yaml) npm package to `package.json` (use command `yarn add js-yaml`).
+
+Then create a file at `config/webpacker/global/index.js` with the following:
+
+```js
+const yaml = require('js-yaml')
+const fs = require('fs')
+const path = require('path')
+
+const FILE_ENV_SPLIT = '.'
+const YAML_EXT = '.yml'
+
+let globalConfig = {
+  environment: null,
+  configDirectory: null
+}
+
+const globalConfigure = (options = {}) => {
+  globalConfig = Object.assign({}, globalConfig, options)
+}
+
+const getGlobalConfig = (key) => {
+  let config = {}
+  const filename = path.join(globalConfig.configDirectory, `${key}${YAML_EXT}`)
+  if (fs.existsSync(filename)) {
+    const configurations = yaml.safeLoad(fs.readFileSync(filename, 'utf8'))
+    config = Object.assign({}, config, configurations['default'] || {})
+    config = Object.assign({}, config, configurations[globalConfig.environment] || {})
+
+    const envFilename = path.join(globalConfig.configDirectory, `${key}${FILE_ENV_SPLIT}${globalConfig.environment}${YAML_EXT}`)
+    if (fs.existsSync(envFilename)) {
+      const envConfigurations = yaml.safeLoad(fs.readFileSync(envFilename, 'utf8'))
+      config = Object.assign({}, config, envConfigurations || {})
+    }
+  }
+  return config
+}
+
+module.exports = {
+  globalConfigure,
+  getGlobalConfig
+}
+```
+
+After this, modify file `config/webpacker/environment.js`:
+
+```js
+const path = require('path')
+const {environment} = require('@rails/webpacker')
+const {globalConfigure, getGlobalConfig} = require('./global')
+
+globalConfigure({
+  environment: process.env.RAILS_ENV || 'development',
+  configDirectory: path.resolve(__dirname, '../global')
+})
+
+const sentrySettings = getGlobalConfig('sentry')
+
+environment.plugins.prepend('Environment', new webpack.EnvironmentPlugin({
+  GLOBAL_SENTRY_ENABLED: sentrySettings.enabled,
+  GLOBAL_SENTRY_JS_KEY: sentrySettings.js,
+  ...
+}))
+
+...
+
+module.exports = environment
 ```
 
-And in production:
+Now you can use these `process.env` keys in your code:
 
-``` js
-Global.hosts.web
-=> "myhost.com"
+```js
+import {init} from '@sentry/browser'
+
+if (process.env.GLOBAL_SENTRY_ENABLED) {
+  init({
+    dsn: process.env.GLOBAL_SENTRY_JS_KEY
+  })
+}
 ```
 
 ## Contributing to global
@@ -285,6 +428,12 @@ Global.hosts.web
 * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
 * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
 
-## Copyright
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/railsware/global/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
 
-Copyright (c) Railsware LLC. See LICENSE.txt for further details.
+Everyone interacting in the Global project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/railsware/global/blob/master/CODE_OF_CONDUCT.md).