global 0.2.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ff7ffaa8d2e0f5e244d2a8afbe0d8e938cea9244
-  data.tar.gz: 8153165733bd12e6c4673c39abdbb16b706a7fc6
+SHA256:
+  metadata.gz: 0da470ddbf97c73984898898bbada287d1fef733da1059016dbe7021a6b4e55a
+  data.tar.gz: b5cf15fb7e5a9e4e9cb7b30a0bf1265a374693d6f1423b95940976c9beeca3f0
 SHA512:
-  metadata.gz: efa24df45cb25c916773f4ff7c1dcc0621421016f567a54af18f77bae41a9242e9dd9a5f5bf942db4db8e133f0b17d971fed83de28fd787cf301859d035b5d61
-  data.tar.gz: 01156ae25535c3d559da859c6717feb59c07510291e23306920e722d35bf3c8c112b789c61d633ec7dc1d019f9ee36380c9889c56b1c7a5e990a2b79930363ff
+  metadata.gz: cbd030fd6ced5e6e3f0d47d75d14f59e16a69411814b1432f0bf66fb03444950006a87b86eed155f758c4a5535eb6e8d9d870edbecdc26c9a66b2a9230384e82
+  data.tar.gz: b99c7b6c92c33324834ad7fd92c75606a9abddbe7d8fe0fbe22b344013000a49073ece171b8063713b370d2c6526c6c0eee928584c90317e5592034506bc3790

data/.github/workflows/tests.yml

@@ -0,0 +1,24 @@
+name: Runs linter and tests
+
+on: [push, pull_request]
+
+jobs:
+  linters_and_tests:
+    runs-on: ${{ matrix.os }}-latest
+    continue-on-error: ${{ matrix.experimental == true }}
+    name: Linter and tests on ${{ matrix.os }}-ruby-${{ matrix.ruby-version }}
+    strategy:
+      matrix:
+        os: [ubuntu, macos]
+        ruby-version: ['3.1', '3.0', '2.7', '2.6', '2.5']
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+
+    - name: Runs linter and tests
+      run: bundle exec rake

data/.rubocop.yml

@@ -0,0 +1,110 @@
+Metrics/MethodLength:
+  Enabled: true
+  Max: 11
+
+Layout/EmptyLinesAroundBlockBody:
+  Enabled: false
+
+Layout/SpaceInsideBlockBraces:
+  Enabled: true
+  EnforcedStyle: space
+  EnforcedStyleForEmptyBraces: no_space
+  SpaceBeforeBlockParameters: true
+
+Layout/SpaceBeforeBlockBraces:
+  Enabled: true
+  EnforcedStyle: space
+  EnforcedStyleForEmptyBraces: space
+
+Layout/SpaceInsideHashLiteralBraces:
+  Enabled: true
+  EnforcedStyle: compact
+  EnforcedStyleForEmptyBraces: no_space
+
+Layout/EmptyLinesAroundClassBody:
+  Enabled: true
+  EnforcedStyle: empty_lines_except_namespace
+
+Layout/EmptyLinesAroundModuleBody:
+  Enabled: true
+  EnforcedStyle: empty_lines_except_namespace
+
+Layout/MultilineMethodCallIndentation:
+  Enabled: true
+  EnforcedStyle: indented
+
+Layout/HashAlignment:
+  Enabled: true
+  EnforcedLastArgumentHashStyle: always_ignore
+
+Lint/RaiseException:
+  Enabled: true
+
+Lint/StructNewOverride:
+  Enabled: true
+
+Style/RaiseArgs:
+  EnforcedStyle: compact
+
+Style/YodaCondition:
+  Enabled: false
+
+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/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+
+Style/Documentation:
+  Enabled: false
+
+Style/SafeNavigation:
+  Enabled: true
+  AllowedMethods:
+    - present?
+    - blank?
+    - presence
+
+Lint/AmbiguousBlockAssociation:
+  Exclude:
+    - "spec/**/*"
+
+Naming/PredicateName:
+  Exclude:
+    - "spec/**/*"
+
+Style/NumericPredicate:
+  Exclude:
+    - "spec/**/*"
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - "spec/**/*"
+
+Metrics/AbcSize:
+  Max: 22
+  Exclude:
+    - "spec/**/*"
+
+Style/ModuleFunction:
+  EnforcedStyle: extend_self

data/.ruby-version

@@ -1 +1 @@
-2.4.1
+2.6.6

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/Gemfile

@@ -1,9 +1,6 @@
-source "http://rubygems.org"
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in global.gemspec
 gemspec
-
-if RUBY_VERSION < "2.2.2"
-  # activesupport 5+ requires MRI 2.2.2+
-  gem "activesupport", "< 5.0.0"
-end

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)
+# Global [![Runs linter and tests](https://github.com/railsware/global/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/railsware/global/actions/workflows/tests.yml) [![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,36 +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.backend(:filesystem, environment: "YOUR_ENV_HERE", path: "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.backend :filesystem, environment: "YOUR_ENV_HERE", path: "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.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.environment = Rails.env.to_s
-  config.config_directory = Rails.root.join('config/global').to_s
+  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:
@@ -62,9 +101,28 @@ In the development environment we now have:
 => "api.localhost"
 ```
 
-### Namespacing
+#### Deserialize other classes from `.yml`
 
-Config file `config/global/web/basic_auth.yml` with:
+Config file `config/global/validations.yml`:
+
+```yml
+default:
+  regexp:
+    email: !ruby/regexp /.@.+\../
+```
+
+Ensure that `Regexp` is included in the `yaml_whitelist_classes` array
+
+```ruby
+Global.validations.regexp.email === 'mail@example.com'
+=> true
+```
+
+#### Per-environment sections
+
+You can define environment sections at the top level of every individual YAML file
+
+For example, having a config file `config/global/web/basic_auth.yml` with:
 
 ```yml
 test:
@@ -78,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
@@ -87,7 +145,7 @@ After that in development environment we have:
 => "development_user"
 ```
 
-### Default section
+#### Default section
 
 Config file example:
 
@@ -102,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:
@@ -124,8 +183,41 @@ Nested options can then be accessed as follows:
 => "development value"
 ```
 
+#### Environment files
+
+Config file `global/aws.yml` with:
+```yml
+:default:
+  activated: false
 
-### ERB support
+staging:
+  activated: true
+  api_key: 'nothing'
+
+```
+
+And file `global/aws.production.yml` with:
+```yml
+:activated: true
+:api_key: 'some api key'
+:api_secret: 'some secret'
+
+```
+
+Provide such configuration on `Global.environment = 'production'` environment:
+
+```ruby
+> Global.aws.activated
+=> true
+> Global.aws.api_key
+=> 'some api key'
+> Global.aws.api_secret
+=> 'some secret'
+```
+
+**Warning**: files with dot(s) in name will be skipped by Global (except this env files).
+
+#### ERB support
 
 Config file `global/file_name.yml` with:
 
@@ -145,79 +237,191 @@ 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.
+
+#### Usage with Go
+
+You can reuse the same configuration in your Go services. For this, we developed a Go module that loads the same configuration tree into Go structs.
+
+See [github.com/railsware/go-global](https://github.com/railsware/go-global) for further instructions.
+
+#### 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.
 
-### Advanced Configuration
+Refer to the [official documentation](https://cloud.google.com/secret-manager/docs) to set up the secret manager.
 
-In case you need different configurations for different parts of your application, you should create the files manually.
+Some steps you will need to follow:
 
-If your application has `admin` and `application` namespace:
+- 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).
 
-```erb
-# app/assets/javascripts/admin/global.js.erb
-<%= Global.generate_js(namespace: "AdminSettings", only: %w(admin hosts)) %>
+#### Configuration examples
 
-# app/assets/javascripts/admin.js.coffee
-#= require admin/global
-``` 
+Backend setup:
 
-```erb
-# app/assets/javascripts/application/global.js.erb
-<%= Global.generate_js(namespace: "AppSettings", except: %w(admin credentials)) %>
+```ruby
+# in config/environments/development.rb
+# you don't need to go to Parameter Store for dev machines
+Global.backend(:filesystem)
 
-# app/assets/javascripts/application.js.coffee
-#= require application/global
+# in config/environments/production.rb
+# enterprise grade protection for your secrets
+Global.backend(:gcp_secret_manager, prefix: 'prod-myapp-', project_id: 'example')
 ```
 
-### Usage
+Create secrets:
 
-Config file example `global/hosts.yml`:
+```
+prod-myapp-basic_auth-username => "bill"
+prod-myapp-basic_auth-password => "secret"
+prod-myapp-api_endpoint => "https://api.myapp.com"
+```
 
-```yml
-development:
-  web: localhost
-  api: api.localhost
-production:
-  web: myhost.com
-  api: api.myhost.com
+Get configuration in the app:
+
+```ruby
+# Encrypted parameters are automatically decrypted:
+> Global.basic_auth.password
+=> "secret"
+> Global.api_endpoint
+=> "https://api.myapp.com"
 ```
-After that in development environment we have:
 
-``` js
-Global.hosts.web
-=> "localhost"
+### Reload configuration data
+
+```ruby
+> Global.reload!
 ```
 
-And in production: 
+## 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'
 
-``` js
-Global.hosts.web
-=> "myhost.com"
+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
+```
+
+Now you can use these `process.env` keys in your code:
+
+```js
+import {init} from '@sentry/browser'
+
+if (process.env.GLOBAL_SENTRY_ENABLED) {
+  init({
+    dsn: process.env.GLOBAL_SENTRY_JS_KEY
+  })
+}
 ```
 
 ## Contributing to global
@@ -230,7 +434,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).
 
-Copyright (c) Railsware LLC. See LICENSE.txt for further details.
+## Code of Conduct
 
+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).