ultra_settings 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f277e747e90903a62b41f8e79074dcd6d8790f160eda187cb03a89f8fdf5df40
-  data.tar.gz: d6054c97b25ed971ec4601e522e5b7c6b1921a5d60d94e761b360b1f09bbc00c
+  metadata.gz: 6740e40d7198c0cb0573b24f5e61c0f679e8fb62b0c18bee3ee79a29748bc908
+  data.tar.gz: d35bb1603d4acfedcf32c8cc7c6063e0deeabb47e825d646ff104568a30de898
 SHA512:
-  metadata.gz: cbf68fab75a43227bcddb7b0db63c42090910a89f55a264c9fd3e731a0dfc1b05cdb834acd549e8215c76cc0b049f57b500e2d1b85081ae75e70efd1eb8a3e53
-  data.tar.gz: 13302c44130fa23473fddf517c768ef963ee505d9ddb2f71ad3bcd8d24261e2dfce562705490d553ef8b0883519485c615dca0c0c0dad1e47efbcf24ce2be49b
+  metadata.gz: 4f4e91264bd4466d0509f813a8b33391a15645ec939395055c353b1d0e162a6de0c89ea78f84139bdffeae3b61033652b58cb373d7cde47b4ee559923e2fe8a5
+  data.tar.gz: 341535915553d7d4d906c79850c4d42630c115ed030fae69b2e851042b999a654982ec7416a120195e65c0b436587b75e330259d675308facea3dedc5db59b98

data/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.1.0
+
+### Added
+
+- Revamped web UI that can now display setting values.
+- Added option to specify fields as a secret in the configuration to prevent exposing sensitive information in the web interface. By default all fields are considered secrets. This can be changed per configuration by setting the `fields_secret_by_default` property to `false`.
+- Added `UltraSettings::ConfigurationView` which can be used to embed the HTML table showing the configuration options and values other admin views. So now you can integrate the settings view into your own admin tools.
+- Add `__to_hash__` method to `UltraSettings::Configuration` which can to serialize the current configuration values as a hash. This value can be used for comparing configuration between environments.
+
+## 1.0.1
+
+### Added
+- Optimize object shapes for the Ruby interpreter by declaring instance variables in constructors.
+
 ## 1.0.0
 
 ### Added

data/README.md

@@ -2,20 +2,29 @@
 
 [![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)
+[![Gem Version](https://badge.fury.io/rb/ultra_settings.svg)](https://badge.fury.io/rb/ultra_settings)
 
-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.
+## Introduction
 
-It allows you to define a hierarchy with three layers of sources for your configuration values:
+UltraSettings is a Ruby gem designed for managing application settings from various sources providing a consistent method for accessing configuration values. It simplifies your application's configuration management by allowing settings to be defined, documented, and accessed seamlessly.
 
-1. Environment variables
-2. Runtime settings (i.e. settings updatable from within the running application)
-3. YAML configuration files
+UltraSettings emphasizes well-documented configuration. You can include documentation directly in the configuration code. The gem also includes a [web UI](#web-ui) that can be mounted as a Rack app or embedded in other views allowing admin users to easily view configuration settings and documentation.
 
-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.
+## Key Features
 
-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.
+This gem supports a three-layer hierarchy for defining configuration sources:
 
-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:
+1. Environment Variables
+2. Runtime Settings (modifiable within the running application)
+3. YAML Configuration Files
+
+Settings from higher levels override those from lower ones. For example, values defined in environment variables or runtime settings will override those specified in YAML files. This hierarchy is optional — you can disable it and define specific data sources as needed for each configuration field.
+
+### Simplified Access and Type Safety
+
+With UltraSettings, your application code does not need to worry about how or from where a setting value is loaded from. Configuration settings can be accessed using plain Ruby objects and methods simplifying the development process.
+
+The gem also ensures type safety by typecasting settings to specific data types, so you can rely on consistent data formats without manual type coercion. Supported types include:
 
 - `String`
 - `Integer`
@@ -25,34 +34,39 @@ Settings are also type cast so you can always be assured that values are returne
 - `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.
+Additionally, you can define default values for settings, ensuring that a fallback value is available if a configuration is missing or does not meet constraints.
 
 ## 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).
+Configurations are defined as classes that extend from the `UltraSettings::Configuration` class. These 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
+  self.fields_secret_by_default = false
+
+  field :host, type: :string, description: "The hostname for the service"
 
-  field :port, type: :integer, default: 80
+  field :port, type: :integer, default: 80, description: "The port for the service"
 
-  field :protocol, type: :string, default: "https"
+  field :protocol, type: :string, default: "https", description: "The protocol for the service"
 
-  field :timeout, type: :float, default: 1.0, default_if: ->(val) { val <= 0 }
+  field :timeout,
+    type: :float,
+    default: 1.0,
+    default_if: ->(val) { val <= 0 },
+    description: "Network timeout in seconds for requests to the service."
 
   field :auth_token,
     type: :string,
     env_var: "MY_SERVICE_TOKEN",
     runtime_setting: false,
     yaml_key: false,
-    description: "Bearer token for accessing the service"
+    description: "Bearer token for accessing the service",
+    secret: true
 
   # You aren't limited to just defining fields, you can define other
   # helper methods to make using the configuration easier.
@@ -62,51 +76,67 @@ class MyServiceConfiguration < UltraSettings::Configuration
 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:
+#### Field Options
+
+You can customize the behavior of each field using various options:
+
+- `:type` -  Specifies the type of the field. The value of the setting will be cast to this type. If the value in the data source cannot be cast to the data type, then it will not be used. Supported types are:
 
   - `:string` (the default)
   - `:integer`
   - `:float`
-  - `:boolean`
+  - `:boolean` (will accept case insensitive strings "true", "false", "1", "0", "t", "f", "yes", "no", "y", "n")
   - `: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.
+- `:description` - Provides a description of the field. This is used for documentation purposes.
+
+- `:default` - Sets a default value for the field. The value will be cast to the specified 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.
+- `:default_if` - Provides a condition for when the default should be used. This should be a Proc or the name of a method within the class. Useful for ensuring values meet specific constraints. This can provide protection from misconfiguration that can break the application. In the above example, the default value for `timeout` will be used if the value is less than or equal to 0.
 
-- You can describe what your setting does with the `:description` option. This value is only for documentation purposes.
+- `:secret` - Marks the field as secret. Secret fields are not displayed in the web UI. By default, all fields are considered secret to avoid accidentally exposing sensitive values. You can change this default behavior by setting `fields_secret_by_default` to `false` either globally or per configuration.
 
-- 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.
+- `:env_var` - Overrides the environment variable name used to populate the field. This is useful if the variable name does not follow the conventional pattern. 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.
+- `:runtime_setting` - Overrides the runtime setting name for the field. Useful if the runtime setting name does not match the conventional pattern. Set this to `false` to disable loading the field from runtime settings.
 
-- 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.
+- `:yaml_key` - Overrides the key in the YAML configuration file for this field. This is useful when the key does not match the field name. Set this to `false` to disable loading the field from a YAML file.
 
-- 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.
+- `:static` - Marks the field as a static value. Static values cannot be changed once set and are not allowed to be set from runtime settings. Use this for settings that need to be referenced at the application is initializing.
 
 ### Environment Variables
 
-Settings will first try to load values from environment variables. Environment variables are a good place to define environment specific values.
+Settings will first try to load values from environment variables. Environment variables are a good place to define environment specific values or sensitive values that you do not want to store in your codebase.
+
+#### Default Behavior
+
+By default, environment variables for settings are constructed using a prefix based on the configuration class name, with the field name appended. For example, a class named `Configs::MySettingsConfiguration` will use the prefix `CONFIGS_MY_SETTINGS_`, resulting in environment variables like `CONFIGS_MY_SETTINGS_HOST`.
 
-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.
+#### Customizing Environment Variables
 
-You can use lowercase environment variable names by setting `env_var_upcase` to `false` on your configuration class.
+You can customize the behavior of environment variable naming in several ways:
 
-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".
+- **Explicit Environment Variables:** You can specify the name of the environment variable to use for a field by setting the `env_var` option on the field. This allows you to use a different name than the default.
 
-You can set an explicit prefix by setting `env_var_prefix` on your configuration class.
+- **Lowercase Environment Variables:** Set `env_var_upcase` to false in your configuration class to use lowercase environment variable names.
 
-You can disable environment variables as a default source on your fields by setting `environment_variables_disabled` to `true` on your configuration class.
+- **Custom Delimiter:** The delimiter between module names and before the setting name can be customized by setting `env_var_delimiter` on your configuration class. For example, using a delimiter of "." in `Configs::MySettingsConfiguration` would produce environment variables like `CONFIGS.MY_SETTINGS.HOST`.
+
+- **Custom Prefix:** Set `env_var_prefix` on your configuration class to specify an explicit prefix for environment variables. This allows for more flexibility in naming conventions.
+
+- **Disabling Environment Variables:** You can disable environment variables as a default source for fields by setting `environment_variables_disabled` to `true` in your configuration class. You can disable environent variables on individual fields by setting `env_var` on the field to `false`.
 
 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.
+Runtime settings are configurations loaded while your application is running, allowing for dynamic updates without needing to restart the application. This flexibility makes them ideal for settings that may change frequently or need quick adjustments.
+
+#### Setting Up Runtime Settings
 
-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.
+To enable runtime settings, set the `UltraSettings.runtime_settings` attribute to an object that implements a `[]` method and accepts a string argument. For example, to load runtime settings from a Redis database, you could use the following implementation:
 
 ```ruby
 class RedisRuntimeSettings
@@ -122,39 +152,57 @@ 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.
+#### Using the `super_settings` gem
+
+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.
 
 ```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.
+#### Customizing Runtime Settings
+
+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 (e.g. `configs.my_settings.host`). By default runtime settings will be in all lowercase letters.
+
+You can customize the behavior of runtime setting names with the following options:
 
-You can use uppercase runtime setting names by setting `runtime_setting_upcase` to `true` on your configuration class.
+- **Explicit Runtime Setting Names:** You can specify the name of the runtime setting to use for a field by setting the `runtime_setting` option on the field. This allows you to use a different name than the default.
 
-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".
+- **Uppercase Runtime Setting Names:** Set `runtime_setting_upcase` to true in your configuration class to use uppercase runtime setting names.
 
-You can set an explicit prefix by setting `runtime_setting_prefix` on your configuration class.
+- **Custom Delimiter:** Change the delimiter used between module names and before the setting name by setting `runtime_setting_delimiter` on your configuration class. For example, using a delimiter of "/" would produce runtime settings like `configs/my_settings/host`.
 
-You can disable runtime settings as a default source on your fields by setting `runtime_settings_disabled` to `true` on your configuration class.
+- **Custom Prefix:** Set `runtime_setting_prefix` on your configuration class to specify a custom prefix for runtime settings, giving you flexibility in naming conventions.
+
+- **Disabling Runtime Settings:** You can disable runtime settings as a default source for fields by setting `runtime_settings_disabled` to `true` in your configuration class. You can disable runtime settings on individual fields by setting `runtime_setting` on the field to `false`.
 
 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.
+YAML files are the final source UltraSettings will check when loading configuration values. They provide a convenient way to store default values that 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 is searched for in the path defined by `UltraSettings.yaml_config_path`. If the file does not exist, the YAML source strategy will not be used.
+
+#### Customizing YAML Files
+
+- **Explicit YAML Key:** You can specify the key in the YAML file to use for a field by setting the `yaml_key` option on the field. This allows you to use a different key than the default.
+
+- **Custom YAML File Path:** You can specify an explicit YAML file by setting `configuration_file` on your configuration class to the desired file path.
 
-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.
+- **Disable YAML Source:** To disable YAML files as a default source for your fields, set `yaml_config_disabled` to true on your configuration class. You can disable YAML files on individual fields by setting `yaml_key` on the field to `false`.
 
-You can specify an explicit YAML file to use by setting `configuration_file` on your configuration class to the path to the file.
+#### ERB Support
 
-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 support ERB markup (i.e., <%= %>) that will be evaluated before the YAML is parsed. This feature allows for dynamically generated values within the YAML file.
 
-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.
+#### Environment-Specific Configurations
 
-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.
+YAML files can define environment-specific configurations. The file must contain a hash where the keys represent the names of your application environments (e.g., `development`, `test`, `production`). You can specify the environment to use by setting `UltraSettings.yaml_config_env` (default is "development").
 
-So, for this YAML file:
+A special key, `shared`, can be defined in the YAML file. The settings under this key will be merged with the environment-specific settings. Values from the specific environment will always overwrite those from `shared`.
+
+#### Example YAML File
 
 ```yaml
 shared:
@@ -169,7 +217,7 @@ production:
   host: prod.example.com
 ```
 
-The values for the "development" environment would be the combination of development and shared:
+The values for the development environment would be the combination of `development` and `shared`:
 
 ```ruby
 {
@@ -179,7 +227,7 @@ The values for the "development" environment would be the combination of develop
 }
 ```
 
-While for "production", the values would be the combination of production and shared:
+While for production, the values would be the combination of `production` and `shared`:
 
 ```ruby
 {
@@ -189,13 +237,13 @@ While for "production", the values would be the combination of production and sh
 }
 ```
 
-Values for the environment will always overwrite values from the shared hash.
+#### Rails Integration
 
 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.
+If you prefer not to use the default hierarchy of environment variables, runtime settings, and YAML files, you can disable it. This allows you to explicitly define which data sources should be used for each field.
 
 ```ruby
 class MyServiceConfiguration < UtraSettings::Configuration
@@ -219,25 +267,30 @@ UltraSettings.yaml_config_disabled = true
 
 ### Accessing settings
 
-Configurations are singleton objects. Settings are accessed by calling methods.
+Configurations in UltraSettings are singleton objects, and settings are accessed by calling methods directly on these objects.
 
 ```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`).
+#### Adding Configurations to UltraSettings
+
+To simplify access, you can add configurations to the `UltraSettings` object. UltraSettings will derive the configuration class name based on the name provided and define a method that returns the configuraiton object. For example:
+
 ```ruby
 UltraSettings.add(:my_service)
+UltraSettings.my_service # => MyServiceConfiguration.instance
 UltraSettings.my_service.host
 ```
 
-You can also specify the class name to map to a different method name.
+Alternatively, you can explicitly specify the class name to map to a 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.
+In a Rails application, you could add syntactic sugar by exposing the `UltraSettings` object as a helper method in application.rb.
 
 ```ruby
 module MyApp
@@ -251,7 +304,10 @@ end
 Rails.application.settings.my_service.host
 ```
 
-You can also keep things clean if your configuration is mostly accessed from within another class.
+#### Using a Helper Method
+
+To keep your codebase clean, especially if most configurations are accessed from within a specific class, you can encapsulate the configuration access in a helper method.
+
 
 ```ruby
 class MyService
@@ -268,11 +324,16 @@ 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.
+UltraSettings provides a web UI via a mountable Rack application. You can use this to view the settings values and documentation. The UI will not display the value of any setting marked as secret.
 
 ![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.
+It is strongly recommended to secure the web UI with your application's authorization framework so that it is only visible to internal admin users.
+
+#### Mounting the Web UI in a Rails Application
+
+Below is an example of mounting the web UI in a Rails application using HTTP Basic authentication.
+
 
 ```ruby
 # config/routes.rb
@@ -285,13 +346,26 @@ mount Rack::Builder.new do
 end, at: "/ultra_settings"
 ```
 
-### Testing
+#### Embedding the Settings View in Admin Tools
+
+If you prefer to embed the settings view directly into your own admin tools or dashboard, you can use the `UltraSettings::ConfigurationView` class to render the settings interface within your existing views:
+
+```erb
+<h1>My Service Settings</h1>
+
+<%= UltraSettings::ConfigurationView.new(MyServiceConfiguration.instance).render %>
+```
+
+This approach allows for seamless integration of the settings UI into your application's admin interface, leveraging your existing authentication and authorization mechanisms. The settings are rendered in an HTML table which you can format with your own CSS.
 
-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:
+### Testing With UltraSettings
+
+When writing automated tests, you may need to override configuration settings to test different scenarios. UltraSettings provides the `UltraSettings.override!` method to temporarily change settings within a test block. Below are examples of how to override the `TestConfiguration#foo` value in a test.
 
 ```ruby
-# Override a configuration added on the global namespace
+# Override a configuration added on the global namespace.
 
+# Note: you must have already added the configuration with UltraSettings.add(:test)
 UltraSettings.override!(test: {foo: "bar"}) do
   expect(TestConfiguration.instance.foo).to eq "bar"
 end
@@ -309,14 +383,17 @@ TestConfiguration.instance.override!(foo: "bar") do
 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.
+#### RSpec Integration
+
+If you are using RSpec, you can simplify overriding settings by setting up a global around hook. This hook will check for the presence of a :settings metadata key and apply the overrides automatically within the test block.
+
 
 ```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
+  config.around(:each, :settings) do |example|
+    if example.metadata[:settings].is_a?(Hash)
+      UltraSettings.override!(example.metadata[:settings]) do
         example.run
       end
     else
@@ -324,13 +401,19 @@ RSpec.configure do |config|
     end
   end
 end
+```
+
+With this setup, you can easily specify settings overrides within individual test blocks using metadata:
 
-# In a test
-it 'has the settings I want', ultra_settings: {test: {foo: "bar"}} do
+```ruby
+it 'has the settings I want', settings: {test: {foo: "bar"}} do
   expect(UltraSettings.test.foo).to eq("bar")
 end
 ```
 
+This approach keeps your tests clean and readable while allowing for flexible configuration management during testing.
+
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0

data/app/application.css

@@ -28,39 +28,18 @@
   background-color: rgba(0, 0, 0, .03);
 }
 
-.ultra-settings-code {
+.ultra-settings-table 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 {
+  color: darkred;
   font-weight: 600;
-  color: blue;
 }
 
-.ultra-settings-description {
-  font-size: 0.9rem;
+.ultra-settings-table em {
   color: gray;
-}
-
-.ultra-settings-info {
-  margin-bottom: 1rem;
-}
-
-.ultra-settings-error {
-  color: darkred;
-}
-
-.ultra-settings-not-applicable {
-  color: #999;
   font-style: italic;
+  font-size: 0.9rem;
 }
 
 .ultra-settings-select {

data/app/configuration.html.erb

@@ -0,0 +1,134 @@
+  <table class="<%= html_escape(table_class.to_s) %>">
+    <thead>
+      <% unless configuration.class.yaml_config_disabled? || configuration.class.configuration_file.nil? %>
+        <tr>
+          <th colspan="6">
+            Configuration File:
+            <span style="font-weight: normal;">
+              <%= html_escape(relative_path(configuration.class.configuration_file)) %>
+              <% unless configuration.class.configuration_file&.exist? %>
+                <em>(File does not exist)</em>
+              <% end %>
+            </span>
+          </th>
+        </tr>
+      <% end %>
+      <tr>
+        <th>Name</th>
+        <th>Value</th>
+        <th>Type</th>
+        <th>Notes</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% configuration.class.fields.each do |field| %>
+        <% source = configuration.__source__(field.name) %>
+        <tr>
+          <td>
+            <code><%= html_escape(field.name) %></code>
+          </td>
+
+          <td style="word-wrap: break-word; max-width:30em;">
+            <% if configuration[field.name].nil? %>
+              <em>nil</em>
+            <% elsif field.secret? %>
+              <%= html_escape(secret_value(configuration[field.name])) %>
+            <% else %>
+              <%= html_escape(display_value(configuration[field.name])) %>
+            <% end %>
+          </td>
+
+          <td>
+            <%= html_escape(field.type) %>
+            <%
+              options = []
+              options << 'static' if field.static?
+              options << 'secret' if field.secret?
+            %>
+            <% unless options.empty? %>
+              <div>
+                <em><%= html_escape(options.join(', ')) %></em>
+              </div>
+            <% end %>
+          </td>
+
+          <td>
+            <% unless field.description.to_s.empty? %>
+              <div>
+                <%= html_escape(field.description) %>
+              </div>
+            <% end %>
+
+            <ul style="margin: 0; padding: 0;list-style-type: disc; list-style-position: inside;">
+              <% if field.env_var && !configuration.class.environment_variables_disabled? %>
+                <li>
+                  <% if source == :env %>
+                    <strong>
+                    Currently
+                  <% else %>
+                    Can be
+                  <% end %>
+                  set with the
+                  <code><%= show_defined_value(field.env_var, configuration.__value_from_source__(field.name, :env), field.secret?) %></code>
+                  environment variable.
+                  <% if source == :env %>
+                    </strong>
+                  <% end %>
+                </li>
+              <% end %>
+              <% if field.runtime_setting && !configuration.class.runtime_settings_disabled? %>
+                <li>
+                  <% if source == :settings %>
+                    <strong>
+                    Currently
+                  <% else %>
+                    Can be
+                  <% end %>
+                  set with the
+                  <code><%= show_defined_value(field.runtime_setting, configuration.__value_from_source__(field.name, :settings), field.secret?) %></code>
+                  runtime setting.
+                  <% if source == :settings %>
+                    </strong>
+                  <% end %>
+                </li>
+              <% end %>
+              <% if field.yaml_key && !configuration.class.yaml_config_disabled? %>
+                <li>
+                  <% if source == :yaml %>
+                    <strong>
+                    Currently
+                  <% else %>
+                    Can be
+                  <% end %>
+                  set with the
+                  <code><%= show_defined_value(field.yaml_key, configuration.__value_from_source__(field.name, :yaml), field.secret?) %></code>
+                  key in the configuration file.
+                  <% if source == :yaml %>
+                    </strong>
+                  <% end %>
+                </li>
+              <% end %>
+              <% if field.default.nil? %>
+                <% if source == :default %>
+                  <li>
+                    <strong>Not set</strong>
+                  </li>
+                <% end %>
+              <% else %>
+                <li>
+                  <% if source == :default %>
+                    <strong>
+                      Currently set with the
+                      <%= show_defined_value("default value", field.default, field.secret?) %>.
+                    </strong>
+                  <% else %>
+                    This field has a <%= show_defined_value("default value", field.default, field.secret?) %>.
+                  <% end %>
+                </li>
+              <% end %>
+            </ul>
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>

data/app/index.html.erb

@@ -12,79 +12,7 @@
   <% 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>
+    <%= UltraSettings::ConfigurationView.new(configuration) %>
   </div>
 <% end %>
 

data/lib/ultra_settings/configuration.rb

@@ -33,10 +33,11 @@ module UltraSettings
       # @param yaml_key [String, Symbol] The name of the YAML key to use for the field. By default
       #   this is the name of the field.
       # @return [void]
-      def field(name, type: :string, description: nil, default: nil, default_if: nil, static: nil, runtime_setting: nil, env_var: nil, yaml_key: nil)
+      def field(name, type: :string, description: nil, default: nil, default_if: nil, static: nil, secret: nil, runtime_setting: nil, env_var: nil, yaml_key: nil)
         name = name.to_s
         type = type.to_sym
         static = !!static
+        secret = lambda { fields_secret_by_default? } if secret.nil?
 
         unless name.match?(ALLOWED_NAME_PATTERN)
           raise ArgumentError.new("Invalid name: #{name.inspect}")
@@ -59,7 +60,8 @@ module UltraSettings
           env_var: construct_env_var(name, env_var),
           runtime_setting: (static ? nil : construct_runtime_setting(name, runtime_setting)),
           yaml_key: construct_yaml_key(name, yaml_key),
-          static: static
+          static: static,
+          secret: secret
         )
 
         class_eval <<-RUBY, __FILE__, __LINE__ + 1 # rubocop:disable Security/Eval
@@ -69,7 +71,7 @@ module UltraSettings
         RUBY
 
         if type == :boolean
-          alias_method "#{name}?", name
+          alias_method :"#{name}?", name
         end
       end
 
@@ -306,6 +308,23 @@ module UltraSettings
         get_inheritable_class_attribute(:@yaml_config_env, "development")
       end
 
+      # Sets the default value for the secret property of fields. Individual fields can still
+      # override this value by explicitly setting the secret property. By default, fields are
+      # considered secret.
+      #
+      # @param value [Boolean]
+      # @return [void]
+      def fields_secret_by_default=(value)
+        set_inheritable_class_attribute(:@fields_secret_by_default, !!value)
+      end
+
+      # Check if fields are considered secret by default.
+      #
+      # @return [Boolean]
+      def fields_secret_by_default?
+        get_inheritable_class_attribute(:@fields_secret_by_default, true)
+      end
+
       # Override field values within a block.
       #
       # @param values [Hash<Symbol, Object>]] List of fields with the values they
@@ -419,6 +438,7 @@ module UltraSettings
       @mutex = Mutex.new
       @memoized_values = {}
       @override_values = {}
+      @yaml_config = nil
     end
 
     def [](name)
@@ -449,12 +469,61 @@ module UltraSettings
       end
     end
 
+    # Get the current source for the field.
+    #
+    # @param name [String, Symbol] the name of the field.
+    # @return [Symbol, nil] The source of the value (:env, :settings, :yaml, or :default).
     def __source__(name)
-      field = self.class.send(:defined_fields)[name]
+      field = self.class.send(:defined_fields)[name.to_s]
+      raise ArgumentError.new("Unknown field: #{name.inspect}") unless field
+
       source = field.source(env: ENV, settings: UltraSettings.__runtime_settings__, yaml_config: __yaml_config__)
       source || :default
     end
 
+    # Get the value of the field from the specified source.
+    #
+    # @param name [String, Symbol] the name of the field.
+    # @param source [Symbol] the source of the value (:env, :settings, :yaml, or :default).
+    # @return [Object] The value of the field.
+    def __value_from_source__(name, source)
+      field = self.class.send(:defined_fields)[name.to_s]
+      raise ArgumentError.new("Unknown field: #{name.inspect}") unless field
+
+      case source
+      when :env
+        field.value(env: ENV)
+      when :settings
+        field.value(settings: UltraSettings.__runtime_settings__)
+      when :yaml
+        field.value(yaml_config: __yaml_config__)
+      when :default
+        field.default
+      else
+        raise ArgumentError.new("Unknown source: #{source.inspect}")
+      end
+    end
+
+    # Output the current state of the configuration as a hash. If the field is marked as a secret,
+    # then the value will be a secure hash of the value instead of the value itself.
+    #
+    # The intent of this method is to provide a serializable value that captures the current state
+    # of the configuration without exposing any secrets. You could, for instance, use the output
+    # to compare the configuration of you application between two different environments.
+    #
+    # @return [Hash]
+    def __to_hash__
+      payload = {}
+      self.class.fields.each do |field|
+        value = self[field.name]
+        if field.secret? && !value.nil?
+          value = "securehash:#{Digest::MD5.hexdigest(Digest::SHA256.hexdigest(value.to_s))}"
+        end
+        payload[field.name] = value
+      end
+      payload
+    end
+
     private
 
     def __get_value__(name)
@@ -509,7 +578,7 @@ module UltraSettings
     end
 
     def __yaml_config__
-      @yaml_config ||= (self.class.load_yaml_config || {})
+      @yaml_config ||= self.class.load_yaml_config || {}
     end
   end
 end

data/lib/ultra_settings/configuration_view.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module UltraSettings
+  # This class can render information about a configuration in an HTML table. It is used by the
+  # bundled web UI, but you can use it to embed the configuration information in your own web pages.
+  #
+  # The output will be an HTML table. You can specify the CSS class for the table by passing the
+  # `table_class` option to the `render` method. By default the table will have the class
+  # `ultra-settings-table`.
+  #
+  # @example
+  #  <h1>Service Configuration</h1>
+  #  <%= UltraSettings::ConfigurationView.new(ServiceConfiguration.instance).render(table_class: "table table-striped") %>
+  class ConfigurationView
+    @template = nil
+
+    class << self
+      def template
+        @template ||= ERB.new(read_app_file("configuration.html.erb"))
+      end
+
+      private
+
+      def read_app_file(path)
+        File.read(File.join(app_dir, path))
+      end
+
+      def app_dir
+        File.expand_path(File.join("..", "..", "app"), __dir__)
+      end
+    end
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def render(table_class: "ultra-settings-table")
+      configuration = @configuration
+      html = self.class.template.result(binding)
+      html = html.html_safe if html.respond_to?(:html_safe)
+      html
+    end
+
+    def to_s
+      render
+    end
+
+    private
+
+    def html_escape(value)
+      ERB::Util.html_escape(value)
+    end
+
+    def display_value(value)
+      case value
+      when Time
+        value.iso8601
+      else
+        value.inspect
+      end
+    end
+
+    def show_defined_value(label, value, secret)
+      title = if value.nil?
+        "Not set"
+      elsif secret
+        "Secret value"
+      else
+        "Value: #{display_value(value)}"
+      end
+      "<dfn title=\"#{html_escape(title)}\">#{html_escape(label)}</dfn>"
+    end
+
+    def secret_value(value)
+      if value.nil?
+        "nil"
+      else
+        "••••••••••••••••"
+      end
+    end
+
+    def relative_path(path)
+      root_path = Pathname.new(Dir.pwd)
+      config_path = UltraSettings::Configuration.yaml_config_path
+      unless config_path.realpath.to_s.start_with?("#{root_path.realpath}#{File::SEPARATOR}")
+        root_path = config_path
+      end
+      path.relative_path_from(root_path)
+    end
+  end
+end

data/lib/ultra_settings/field.rb

@@ -20,6 +20,8 @@ module UltraSettings
     # @param env_var [String, Symbol] The name of the environment variable to use for the field.
     # @param runtime_setting [String, Symbol] The name of the setting to use for the field.
     # @param yaml_key [String, Symbol] The name of the YAML key to use for the field.
+    # @param static [Boolean] Whether or not the field is static and cannot be changed at runtime.
+    # @param secret [Boolean] Whether or not the field contains a value that should be kept secret.
     def initialize(
       name:,
       type: :string,
@@ -29,7 +31,8 @@ module UltraSettings
       env_var: nil,
       runtime_setting: nil,
       yaml_key: nil,
-      static: false
+      static: false,
+      secret: false
     )
       @name = name.to_s.freeze
       @type = type.to_sym
@@ -40,13 +43,14 @@ module UltraSettings
       @runtime_setting = runtime_setting&.to_s&.freeze
       @yaml_key = yaml_key&.to_s&.freeze
       @static = !!static
+      @secret = (secret.respond_to?(:call) ? secret : !!secret)
     end
 
     # Get the value for the field from the passed in state.
     #
-    # @param env [#[]] The environment variables.
-    # @param settings [#[]] The runtime settings.
-    # @param yaml_config [#[]] The YAML configuration.
+    # @param env [Hash, nil] The environment variables.
+    # @param settings [Hash, nil] The runtime settings.
+    # @param yaml_config [Hash, nil] The YAML configuration.
     def value(env: nil, settings: nil, yaml_config: nil)
       fetch_value_and_source(env: env, settings: settings, yaml_config: yaml_config).first
     end
@@ -76,6 +80,17 @@ module UltraSettings
       @static
     end
 
+    # Returns true if the field is marked as having a secret value.
+    #
+    # @return [Boolean]
+    def secret?
+      if @secret.respond_to?(:call)
+        !!@secret.call
+      else
+        @secret
+      end
+    end
+
     private
 
     def fetch_value_and_source(env:, settings:, yaml_config:)

data/lib/ultra_settings/rack_app.rb

@@ -5,6 +5,10 @@ module UltraSettings
   # No setting values are displayed, but you should still add some
   # sort of authentication if you want to use this in production.
   class RackApp
+    def initialize
+      @webview = nil
+    end
+
     def call(env)
       [200, {"content-type" => "text/html; charset=utf8"}, [webview.render_settings]]
     end

data/lib/ultra_settings.rb

@@ -5,12 +5,14 @@ require "yaml"
 require "time"
 require "pathname"
 require "singleton"
+require "digest"
 
 require_relative "ultra_settings/configuration"
 require_relative "ultra_settings/coerce"
 require_relative "ultra_settings/field"
 require_relative "ultra_settings/rack_app"
 require_relative "ultra_settings/web_view"
+require_relative "ultra_settings/configuration_view"
 require_relative "ultra_settings/yaml_config"
 require_relative "ultra_settings/version"
 
@@ -29,6 +31,7 @@ module UltraSettings
 
   @configurations = {}
   @mutex = Mutex.new
+  @runtime_settings = nil
 
   class << self
     # Adds a configuration to the root namespace. The configuration will be
@@ -160,10 +163,14 @@ module UltraSettings
     # @return [Object, nil]
     # @api private
     def __runtime_settings__
-      @runtime_settings ||= nil
+      @runtime_settings
     end
 
-    # Explicitly set setting values within a block. This is useful for testing
+    def fields_secret_by_default=(value)
+      Configuration.fields_secret_by_default = value
+    end
+
+    # Explicitly set values for setting within a block. This is useful for testing
     # or other situations where you want hard code a specific set of values.
     #
     # @param settings [Hash] The settings to set.

data/ultra_settings.gemspec

@@ -4,11 +4,17 @@ Gem::Specification.new do |spec|
   spec.authors = ["Brian Durand"]
   spec.email = ["bbdurand@gmail.com"]
 
-  spec.summary = "Unified application configuration that allows for configuration via environment variables, YAML files, and dynamic runtime setting."
+  spec.summary = "UltraSettings is a Ruby gem that provides a flexible and documented approach to managing application configurations from multiple sources, including environment variables, runtime settings, and YAML files, with an optional web UI for easy documentation."
 
   spec.homepage = "https://github.com/bdurand/ultra_settings"
   spec.license = "MIT"
 
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => spec.homepage,
+    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md"
+  }
+
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   ignore_files = %w[

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ultra_settings
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Brian Durand
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-09-30 00:00:00.000000000 Z
+date: 2024-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -32,17 +32,19 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- MIT-LICENSE
+- MIT-LICENSE.txt
 - README.md
 - VERSION
 - app/application.css
 - app/application.js
+- app/configuration.html.erb
 - app/index.html.erb
 - app/layout.css
 - app/layout.html.erb
 - lib/ultra_settings.rb
 - lib/ultra_settings/coerce.rb
 - lib/ultra_settings/configuration.rb
+- lib/ultra_settings/configuration_view.rb
 - lib/ultra_settings/field.rb
 - lib/ultra_settings/rack_app.rb
 - lib/ultra_settings/railtie.rb
@@ -53,7 +55,10 @@ files:
 homepage: https://github.com/bdurand/ultra_settings
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/bdurand/ultra_settings
+  source_code_uri: https://github.com/bdurand/ultra_settings
+  changelog_uri: https://github.com/bdurand/ultra_settings/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -69,9 +74,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.12
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
-summary: Unified application configuration that allows for configuration via environment
-  variables, YAML files, and dynamic runtime setting.
+summary: UltraSettings is a Ruby gem that provides a flexible and documented approach
+  to managing application configurations from multiple sources, including environment
+  variables, runtime settings, and YAML files, with an optional web UI for easy documentation.
 test_files: []