ultra_settings 0.0.1.rc1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4bf1774f001f4b527b419e5c1f19ed05556a86ecf8f88b0b07df9f828ca3c7b
-  data.tar.gz: a204f002cc7a2a5d0747cd00abd6d64f9b7facb899475a4f9d96c15eeaa8814e
+  metadata.gz: f277e747e90903a62b41f8e79074dcd6d8790f160eda187cb03a89f8fdf5df40
+  data.tar.gz: d6054c97b25ed971ec4601e522e5b7c6b1921a5d60d94e761b360b1f09bbc00c
 SHA512:
-  metadata.gz: 1a9a7d61e85e0c0a3cd406535f33e978b1455cfcecb66cf8376ec3d76255540b35e950e39566c86b758004e3d80491d9267c4cccb6b5a889cd964d3b3119afe9
-  data.tar.gz: e6f32cbc8d56496a7486ed05bd388e8ab93229b1df2ac016e56c9fac610dbc39ddd29c89967ae5f2ca1029f8d34919b1bbde451b31c4262adde44adde68dfa8f
+  metadata.gz: cbf68fab75a43227bcddb7b0db63c42090910a89f55a264c9fd3e731a0dfc1b05cdb834acd549e8215c76cc0b049f57b500e2d1b85081ae75e70efd1eb8a3e53
+  data.tar.gz: 13302c44130fa23473fddf517c768ef963ee505d9ddb2f71ad3bcd8d24261e2dfce562705490d553ef8b0883519485c615dca0c0c0dad1e47efbcf24ce2be49b

data/README.md

@@ -1,18 +1,336 @@
-# Unified Rails Configuration :construction:
+# UltraSettings
 
 [![Continuous Integration](https://github.com/bdurand/ultra_settings/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/bdurand/ultra_settings/actions/workflows/continuous_integration.yml)
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
 
-TODO
+This gem provides a method for managing application settings and loading their values from a variety of sources. It can help you get a handle on you application's configuration by providing a consistent method for accessing settings. It also provides a method for documenting your application's settings.
+
+It allows you to define a hierarchy with three layers of sources for your configuration values:
+
+1. Environment variables
+2. Runtime settings (i.e. settings updatable from within the running application)
+3. YAML configuration files
+
+Settings at a higher level will override those set at a lower level. So, for instance, you can override values set in a YAML file with either environment variables or runtime settings. The hierarchy is an optional feature and can be disabled in favor of explicitly defined data sources if you want.
+
+Your application code does not need to concern itself with how a setting value is being loaded or from what source. It can just reference configuration settings using plain old Ruby objects and methods.
+
+Settings are also type cast so you can always be assured that values are returned as a predetermined class and your application does not need to worry about type coercion. The supported types are:
+
+- `String`
+- `Integer`
+- `Float`
+- `Boolean`
+- `Time`
+- `Symbol`
+- `Array<String>`
+
+You can also define default values to be returned in case the configured value is missing or it fails to match a constraint.
+
+Settings are accessed through singleton classes that you define.
 
 ## Usage
 
+### Defining Configurations
+
+Configurations are classes that extend from the `UltraSettings::Configuration` class. Configuration classes are [singleton classes](https://ruby-doc.org/3.2.2/stdlibs/singleton/Singleton.html).
+
+You can define fields on your configuration classes with the `field` method. This will define a method on your configuration object with the given name.
+
+```ruby
+class MyServiceConfiguration < UltraSettings::Configuration
+  field :host, type: :string
+
+  field :port, type: :integer, default: 80
+
+  field :protocol, type: :string, default: "https"
+
+  field :timeout, type: :float, default: 1.0, default_if: ->(val) { val <= 0 }
+
+  field :auth_token,
+    type: :string,
+    env_var: "MY_SERVICE_TOKEN",
+    runtime_setting: false,
+    yaml_key: false,
+    description: "Bearer token for accessing the service"
+
+  # You aren't limited to just defining fields, you can define other
+  # helper methods to make using the configuration easier.
+  def uri
+    URI("#{protocol}://#{host}:#{port}")
+  end
+end
+```
+
+- You can specify a return type with the `:type` option. The value of the setting will be cast to this type. Valid types are:
+
+  - `:string` (the default)
+  - `:integer`
+  - `:float`
+  - `:boolean`
+  - `:datetime`
+  - `:symbol`
+  - `:array` (of strings)
+
+- You can specify a default value with the `:default` option. Note that this value will still be cast to the defined type.
+
+- You can specify a trigger of when the default should be used with the `:default_if` option. If this option is provided, then it should be either a `Proc` or the name of a method in the class to call with the value from the settings. You can use this feature, for example, to always ensure that a value meets certain constraints.
+
+- You can describe what your setting does with the `:description` option. This value is only for documentation purposes.
+
+- You can override the environment variable used to populate the setting with the `:env_var` option. You can use this to point to an environment variable name that does not match the conventional pattern. You can also set this to `false` to disable loading the field from an environment variable.
+
+- You can override the key in the YAML file with the `:yaml_key` option. You can use this to map a setting to a key in the YAML hash if the key doesn't match the field name. You can also set this to `false` to disable loading the field from a YAML file.
+
+- You can override the name of the runtime setting used to populate the setting with the `:runtime_setting` option. You can use this to point to a setting whose name does not match the conventional pattern. You can also set this to `false` to disable loading the field from runtime settings.
+
+- You can define a value as a static value by setting the `:static` option to true. Static values will not be changed once they are set. Static values also cannot be set from runtime settings. If you are referencing a setting during your application's initialization, then you should declare it as a static field.
+
+### Environment Variables
+
+Settings will first try to load values from environment variables. Environment variables are a good place to define environment specific values.
+
+By default settings will be loaded from environment variables by constructing a prefix from the configuration class name (i.e. `Configs::MySettingsConfiguration` uses the prefix `"CONFIGS_MY_SETTINGS_"`) with the field name appended to it. By default environment variables will be in all uppercase letters.
+
+You can use lowercase environment variable names by setting `env_var_upcase` to `false` on your configuration class.
+
+You can use a different delimiter by setting `env_var_delimiter` on your configuration class. The delimiter is used between modules and before the setting name so a delimiter of "." on `Configs::MySettingsConfiguration#setting` would produce "CONFIGS.MY_SETTINGS.SETTING".
+
+You can set an explicit prefix by setting `env_var_prefix` on your configuration class.
+
+You can disable environment variables as a default source on your fields by setting `environment_variables_disabled` to `true` on your configuration class.
+
+If a setting value cannot be loaded from an environment variable, then it's value will attempt to be loaded from a runtime setting.
+
+### Runtime Settings
+
+Runtime settings are settings that are loaded at runtime while your application is running. The advantage to this kind of setting is that your application does not need to restart in order to get an updated value.
+
+To use runtime settings, you need to set the `UltraSettings.runtime_settings` attribute to an object that defines the `[]` method and takes a string as the argument. For instance, if you wanted to load runtime settings from a Redis database, you could implement them like this.
+
+```ruby
+class RedisRuntimeSettings
+  def initialize
+    @redis = Redis.new
+  end
+
+  def [](name)
+    @redis.get(name)
+  end
+end
+
+UltraSettings.runtime_settings = RedisRuntimeSettings.new
+```
+
+There is a companion gem [super_settings](https://github.com/bdurand/super_settings) that can be used as a drop in implementation for the runtime settings. You just need to set the runtime settings to the `SuperSettings` object itself.
+
+```ruby
+UltraSettings.runtime_settings = SuperSettings
+```
+
+By default settings will be loaded from runtime settings by constructing a prefix from the configuration class name (i.e. `Configs::MySettingsConfiguration` uses the prefix `"configs.my_settings."`) with the field name appended to it. By default runtime settings will be in all lowercase letters.
+
+You can use uppercase runtime setting names by setting `runtime_setting_upcase` to `true` on your configuration class.
+
+You can use a different delimiter by setting `runtime_setting_delimiter` on your configuration class. The delimiter is used between modules and before the setting name so a delimiter of "/" on `Configs::MySettingsConfiguration#setting` would produce "configs/my_settings/setting".
+
+You can set an explicit prefix by setting `runtime_setting_prefix` on your configuration class.
+
+You can disable runtime settings as a default source on your fields by setting `runtime_settings_disabled` to `true` on your configuration class.
+
+If a setting value cannot be loaded from the runtime settings, then it's value will attempt to be loaded from a YAML file.
+
+### YAML Files
+
+The last place settings will be loaded from are from static YAML files. These can provide a good place to store default values for you application since they can be distributed with your application code.
+
+By default settings will be loaded from a YAML file determined by its class name (i.e. `Configs::MySettingsConfiguration` uses the file `"configs/my_settings.yml"`). The file will be searched for in the path defined by `UltraSettings.yaml_config_path`. If the file does not exist, then settings will not use the YAML source strategy.
+
+You can specify an explicit YAML file to use by setting `configuration_file` on your configuration class to the path to the file.
+
+You can disable YAML files as a default source on your fields by setting `yaml_config_disabled` to `true` on your configuration class.
+
+YAML files will be evaluated for an ERB markup (i.e. `<%= %>`) before the YAML itself is evaluated. You can use this feature to dynamically generate values within the YAML file.
+
+YAML files define environment specific configurations. YAML files must define a hash where the keys are the names of your application environments (i.e. development, test, production, etc.). You define which environment to use with `UltraSettings.yaml_config_env` (the default environment is "development"). There is also a special key `"shared"` which, if defined, will be merged with the environment hash.
+
+So, for this YAML file:
+
+```yaml
+shared:
+  timeout: 5
+  port: 8000
+
+development:
+  timeout: 10
+  host: localhost
+
+production:
+  host: prod.example.com
+```
+
+The values for the "development" environment would be the combination of development and shared:
+
+```ruby
+{
+  timeout: 10,
+  port: 8000,
+  host: "localhost"
+}
+```
+
+While for "production", the values would be the combination of production and shared:
+
+```ruby
+{
+  timeout: 5,
+  port: 8000,
+  host: "prod.example.com"
+}
+```
+
+Values for the environment will always overwrite values from the shared hash.
+
+In a Rails application, the YAML environment will be set to the Rails environment and YAML files will be assumed to exist in the `config` directory.
+
+### Removing The Hierarchy
+
+If you don't like the default behavior of the hierarchy of environment variables, runtime settings, and YAML files, you can disable it and then explicitly enable only the appropriate data source on each field.
+
+```ruby
+class MyServiceConfiguration < UtraSettings::Configuration
+  self.environment_variables_disabled = false
+  self.runtime_settings_disabled = false
+  self.yaml_config_disabled = false
+
+field :host, yaml_key: "host"
+  field :token, env_var: "MY_SERVICE_TOKEN"
+  field :timeout, runtime_setting: "my_service.timeout", default: 5
+end
+```
+
+If you don't want the hierarchy in any configuration, then you can disable it globally.
+
+```ruby
+UltraSettings.environment_variables_disabled = true
+UltraSettings.runtime_settings_disabled = true
+UltraSettings.yaml_config_disabled = true
+```
+
+### Accessing settings
+
+Configurations are singleton objects. Settings are accessed by calling methods.
+
 ```ruby
+MyServiceConfiguration.instance.host
+```
+
+You can add configurations as methods onto the `UltraSettings` object. By default the configuration class name will be guessed (i.e. "my_service" maps to `MyServiceConfiguration`).
+```ruby
+UltraSettings.add(:my_service)
 UltraSettings.my_service.host
+```
+
+You can also specify the class name to map to a different method name.
+```ruby
+UltraSettings.add(:my, "MyServiceConfiguration")
+UltraSettings.my.host
+```
+
+In a Rails application, you could add some syntactic sugar and expose the `UltraSettings` object as a helper method in application.rb.
+
+```ruby
+module MyApp
+  class Application < Rails::Application
+    def settings
+      UltraSettings
+    end
+  end
+end
 
 Rails.application.settings.my_service.host
 ```
 
+You can also keep things clean if your configuration is mostly accessed from within another class.
+
+```ruby
+class MyService
+
+  # Reference the value as `settings.host`
+
+  private
+
+  def settings
+    MyServiceConfiguration.instance
+  end
+end
+```
+
+### Web UI
+
+There is a web UI available via a mountable Rack application. The UI will only expose the source of where settings are being loaded from. For security reasons, it will not show any of the setting values. It is still highly advised to put it behind whatever authorization framework you application uses.
+
+![Web UI](assets/web_ui.png)
+
+Here is a simple example of how to mount in a Rails application behind HTTP Basic authentication with hard coded credentials.
+
+```ruby
+# config/routes.rb
+
+mount Rack::Builder.new do
+  use Rack::Auth::Basic do |username, password|
+    username == ENV.fetch("AUTH_USER") && password == ENV.fetch("AUTH_PASSWORD")
+  end
+  run UltraSettings::RackApp
+end, at: "/ultra_settings"
+```
+
+### Testing
+
+You can use the `UltraSettings.override!` method to force different configuration settings in you automated tests. Here's examples of overriding the `TestConfiguration#foo` value in a test block:
+
+```ruby
+# Override a configuration added on the global namespace
+
+UltraSettings.override!(test: {foo: "bar"}) do
+  expect(TestConfiguration.instance.foo).to eq "bar"
+end
+
+# or directly on the configuration class
+
+TestConfiguration.override!(foo: "bar") do
+  expect(TestConfiguration.instance.foo).to eq "bar"
+end
+
+# or on the instance itself
+
+TestConfiguration.instance.override!(foo: "bar") do
+  expect(TestConfiguration.instance.foo).to eq "bar"
+end
+```
+
+If you are using RSpec, you can set up a global before handler to make it easier to specify settings within your test blocks.
+
+```ruby
+# RSpec setup
+RSpec.configure do |config|
+  config.around do |example|
+    if example.metadata[:ultra_settings].is_a?(Hash)
+      UltraSettings.override!(example.metadata[:ultra_settings]) do
+        example.run
+      end
+    else
+      example.run
+    end
+  end
+end
+
+# In a test
+it 'has the settings I want', ultra_settings: {test: {foo: "bar"}} do
+  expect(UltraSettings.test.foo).to eq("bar")
+end
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/VERSION

@@ -1 +1 @@
-0.0.1.rc1
+1.0.0

data/app/application.css

@@ -0,0 +1,85 @@
+.ultra-settings-nav {
+  margin-bottom: 1rem;
+}
+
+.ultra-settings-nav form {
+  margin: 0;
+}
+
+.ultra-settings-table {
+  width: 100%;
+  max-width: 100%;
+  margin-bottom: 1rem;
+  border-collapse: collapse;
+}
+
+.ultra-settings-table thead th {
+  vertical-align: bottom;
+  border-bottom: 2px solid #dee2e6;
+}
+
+.ultra-settings-table td, .ultra-settings-table th {
+  padding: 0.75rem;
+  vertical-align: top;
+  border-top: 1px solid #dee2e6;
+}
+
+.ultra-settings-table tbody tr:nth-of-type(odd) {
+  background-color: rgba(0, 0, 0, .03);
+}
+
+.ultra-settings-code {
+  font-family: monospace;
+  font-size: 0.9rem;
+  display: inline;
+}
+
+.ultra-settings-static {
+  color: gray;
+  font-style: italic;
+  font-size: 0.9rem;
+}
+
+.ultra-settings-current-source {
+  font-weight: 600;
+  color: blue;
+}
+
+.ultra-settings-description {
+  font-size: 0.9rem;
+  color: gray;
+}
+
+.ultra-settings-info {
+  margin-bottom: 1rem;
+}
+
+.ultra-settings-error {
+  color: darkred;
+}
+
+.ultra-settings-not-applicable {
+  color: #999;
+  font-style: italic;
+}
+
+.ultra-settings-select {
+  display: inline-block;
+  padding: .375rem 2.25rem .375rem .75rem;
+  -moz-padding-start: calc(0.75rem - 3px);
+  font-size: 1rem;
+  font-weight: 400;
+  line-height: 1.5;
+  color: #212529;
+  background-color: #fff;
+  background-image: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3e%3cpath fill='none' stroke='%23343a40' stroke-linecap='round' stroke-linejoin='round' stroke-width='2' d='M2 5l6 6 6-6'/%3e%3c/svg%3e");
+  background-repeat: no-repeat;
+  background-position: right .75rem center;
+  background-size: 16px 12px;
+  border: 1px solid #ced4da;
+  border-radius: .25rem;
+  transition: border-color .15s ease-in-out,box-shadow .15s ease-in-out;
+  -webkit-appearance: none;
+  -moz-appearance: none;
+  appearance: none;
+}

data/app/application.js

@@ -0,0 +1,19 @@
+document.addEventListener("DOMContentLoaded", () => {
+  const menu = document.getElementById("config-selector");
+
+  showCurrentConfiguration = () => {
+    const selectedId = menu.options[menu.selectedIndex].value;
+
+    document.querySelectorAll(".ultra-settings-configuration").forEach((configuration) => {
+      if (configuration.id === selectedId) {
+        configuration.style.display = "block";
+      } else {
+        configuration.style.display = "none";
+      }
+    });
+  }
+
+  menu.addEventListener("change", showCurrentConfiguration);
+
+  showCurrentConfiguration();
+});

data/app/index.html.erb

@@ -0,0 +1,93 @@
+<div class="ultra-settings-nav">
+  <form onsubmit="return false">
+    <select class="ultra-settings-select" size="1" id="config-selector">
+      <% UltraSettings.__configuration_names__.sort.each do |name| %>
+        <option value="config-<%= name %>"><%= name %></option>
+      <% end %>
+    </select>
+  </form>
+</div>
+
+<% UltraSettings.__configuration_names__.sort.each do |name| %>
+  <% configuration = UltraSettings.send(name) %>
+
+  <div class="ultra-settings-configuration" id="config-<%= name %>" style="display:none;">
+    <% unless configuration.class.yaml_config_disabled? %>
+      <div class="ultra-settings-info">
+        YAML File:
+        <span class="ultra-settings-code <%= 'ultra-settings-error' unless configuration.class.configuration_file %>">
+          <%= configuration.class.configuration_file.to_s.sub(/\A#{Regexp.escape(UltraSettings::Configuration.yaml_config_path.to_s)}\//, "") %>
+        </span>
+      </div>
+    <% end %>
+
+    <table class="ultra-settings-table">
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Type</th>
+          <th>Environment Variable</th>
+          <th>Runtime Setting</th>
+          <th>YAML Key</th>
+          <th>Default</th>
+        </tr>
+      </thead>
+      <tbody>
+        <% configuration.class.fields.sort_by(&:name).each do |field| %>
+          <tr>
+            <td>
+              <%= field.name %>
+              <% unless field.description.to_s.empty? %>
+                <div class="ultra-settings-description">
+                  <%= field.description %>
+                </div>
+              <% end %>
+            </td>
+            <td>
+              <%= field.type %>
+              <% if field.static? %>
+                <div class="ultra-settings-static">
+                  static
+                </div>
+              <% end %>
+            </td>
+              <td>
+              <% if field.env_var && !configuration.class.environment_variables_disabled? %>
+                <pre class="ultra-settings-code <%= 'ultra-settings-current-source' if configuration.__source__(field.name) == :env %>"><%= field.env_var %></pre>
+              <% else %>
+                <span class="ultra-settings-not-applicable">n/a</span>
+              <% end %>
+            </td>
+            <td>
+              <% if field.runtime_setting && !configuration.class.runtime_settings_disabled? %>
+                <pre class="ultra-settings-code <%= 'ultra-settings-current-source' if configuration.__source__(field.name) == :settings %>"><%= field.runtime_setting %></pre>
+              <% else %>
+                <span class="ultra-settings-not-applicable">n/a</span>
+              <% end %>
+            </td>
+            <td>
+              <% if field.yaml_key && !configuration.class.yaml_config_disabled? %>
+                <pre class="ultra-settings-code <%= 'ultra-settings-current-source' if configuration.__source__(field.name) == :yaml %>"><%= field.yaml_key %></pre>
+              <% else %>
+                <span class="ultra-settings-not-applicable">n/a</span>
+              <% end %>
+            </td>
+            <td>
+              <span class="<%= 'ultra-settings-current-source' if configuration.__source__(field.name) == :default %>">
+                <% if field.default.nil? %>
+                  <em>nil</em>
+                <% else %>
+                  &#x2714;
+                <% end %>
+              </span>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+<% end %>
+
+<script>
+  <%= @javascript %>
+</script>

data/app/layout.css

@@ -0,0 +1,27 @@
+* {box-sizing:border-box;}
+
+body {
+  font-family: sans-serif;
+  font-size: 1rem;
+  line-height: 1.5;
+  text-align: left;
+  color: #212529;
+  background-color: #ffffff;
+  margin: 0;
+  padding: 0;
+}
+
+header {
+  background-color: #666;
+  color: white;
+  padding: 1rem;
+  margin-bottom: 1rem;
+}
+
+header h1 {
+  margin: 0;
+}
+
+main {
+  margin: 1rem;
+}

data/app/layout.html.erb

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+
+<html>
+  <head>
+    <title>Application Settings</title>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <style type="text/css">
+      <%= @layout_css %>
+      <%= css %>
+    </style>
+  </head>
+  <body>
+    <header>
+      <h1>Application Settings</h1>
+    </header>
+    <main>
+      <%= content %>
+    </main>
+  </body>
+</html>