ultra_settings 2.6.1 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec11cc8661b191dbb102deec0798f47ef11495feb8675f2f5b83e3e5d752855f
-  data.tar.gz: e3f729687eaad31be948aa8f7b4818f25fb842cec8261058aa1a9f62616639c6
+  metadata.gz: f70521135220d74fe5ef4fbc6261c9d5b8a93f200f898af0fead2ebb7d31cbfd
+  data.tar.gz: 42330a1a294bee7ab53c61f37b56cd0b5b6f309326f1809bfd012cbfcd67fa58
 SHA512:
-  metadata.gz: 455632dc476fc7ed73a70d784d97de612db55c1c2650e31b0896727f9747c8e4ddc3a2bfcdf9c2b190180c4f3d157aca427b75abf68c6e5f312b1251d9f24fc5
-  data.tar.gz: 83e7686584d1ea62747d693c17f9f43908d70a5f5b45541d9f129b2e33e92521b0ce0c87d4c8ec10e3416afd186fefee93f281a6bfa0871c8b56e741d1fc44f6
+  metadata.gz: aab2c06121a67e227f1628d1dd3a22590e0bb174f132506840112278a5c09484e57dd6bc176ddbb35d576388c29bb5f6da462473f1c5ebf76724fe8677312ed2
+  data.tar.gz: f7e9bd08a2958def30780e0ef966d8b90321d3f9c1bf469677b7c51ab8b512e867bf0e1fc1d910d72f24c9f71818a34050b3a2dbfdc2c5adb9afa4a3e048948a

data/CHANGELOG.md

@@ -4,17 +4,24 @@ 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).
 
+## 2.7.0
+
+### Added
+
+- Added new setting to indicate if the runtime settings engine is secure. If the engine is marked as not secure, then runtime settings will be disabled for all fields marked as secret. This protects sensitive information from being exposed in the web UI or through the API. The default value is `true` to maintain backwards compatibility.
+
 ## 2.6.1
 
 ### Added
 
 - Show icons on the web UI that open a dialog with the current value for each data source.
+- Added support for passing the field description in `UltraSettings.runtime_settings_url` using the `${description}` placeholder in the URL.
 
 ## 2.6.0
 
 ### Added
 
-- Added support for passing the type in `UltraSettings.runtime_settings_url` as `${type}` in the URL.
+- Added support for passing the type in `UltraSettings.runtime_settings_url` using the `${type}` placeholder in the URL.
 
 ### Changed
 

data/README.md

@@ -81,7 +81,6 @@ class MyServiceConfiguration < UltraSettings::Configuration
   field :auth_token,
     type: :string,
     env_var: "MY_SERVICE_TOKEN",
-    runtime_setting: false,
     yaml_key: false,
     description: "Bearer token for accessing the service",
     secret: true
@@ -114,7 +113,7 @@ You can customize the behavior of each field using various options:
 
 - `: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.
 
-- `: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.
+- `: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. Additionaly, if you set `UltraSettings.runtime_settings_secure` to false, then runtime settings will be disabled on secret fields.
 
 - `: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.
 
@@ -172,6 +171,9 @@ UltraSettings.runtime_settings = RedisRuntimeSettings.new
 
 The runtime settings implementation may also define an `array` method that takes a single parameter to return an array value. If this method is not implemented, then array values must be returned as single line CSV strings.
 
+> [!TIP]
+> If your runtime settings implementation does not securely store values, you should set `UltraSettings.runtime_settings_secure` to `false`. This will disable runtime settings on fields marked as secret to prevent leaking sensitive information.
+
 #### 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.
@@ -211,7 +213,7 @@ You can customize the behavior of runtime setting names with the following optio
 
 - **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`.
 
-- **Editing Links** You can specify a URL for editing runtime settings from the web UI by setting `UltraSettings.runtime_settings_url` to the desired URL. This will add links to the runtime settings in the web UI. You can use the placeholders `${name}` and `${type}` in the URL which will be replaced with the name and type of the runtime setting, respectively. If you are using the `super_settings` gem for runtime settings, then you can target a setting by adding `#edit=${name}&type=${type}` to the root URL where `super_settings` is mounted.
+- **Editing Links** You can specify a URL for editing runtime settings from the web UI by setting `UltraSettings.runtime_settings_url` to the desired URL. This will add links to the runtime settings in the web UI. You can use the placeholders `${name}`, `${type}`, and `${description}` in the URL which will be replaced with the name, type, and description of the field respectively. If you are using the `super_settings` gem for runtime settings, then you can target a setting by adding `#edit=${name}&type=${type}&description=${description}` to the root URL where `super_settings` is mounted.
 
 If a setting value cannot be loaded from the runtime settings, then it's value will attempt to be loaded from a YAML file.
 

data/VERSION

@@ -1 +1 @@
-2.6.1
+2.7.0

data/app/configuration.html.erb

@@ -73,7 +73,7 @@
               <% if source == :settings %>
                 <span class="ultra-settings-source-indicator">Currently active</span>
               <% end %>
-              <% edit_url = UltraSettings.runtime_settings_url(field.runtime_setting, field.type) %>
+              <% edit_url = UltraSettings.runtime_settings_url(name: field.runtime_setting, type: field.type, description: field.description) %>
               <% if edit_url %>
                 <a href="<%= html_escape(edit_url) %>" class="ultra-settings-edit-link" title="Edit <%= html_escape(field.runtime_setting) %>">
                   <%= edit_icon %>

data/lib/ultra_settings/application_view.rb

@@ -15,23 +15,37 @@ module UltraSettings
   class ApplicationView
     attr_reader :css
 
+    # Initialize the application view with a color scheme.
+    #
+    # @param color_scheme [Symbol] The color scheme to use (:light, :dark, or :system).
     def initialize(color_scheme: :light)
       @css = application_css(color_scheme)
       @css = @css.html_safe if @css.respond_to?(:html_safe)
     end
 
+    # Render the HTML for the configuration settings UI.
+    #
+    # @param select_class [String] CSS class for the select element.
+    # @param table_class [String] CSS class for the table element (for backwards compatibility).
+    # @return [String] The rendered HTML.
     def render(select_class: "ultra-settings-select", table_class: "")
       html = ViewHelper.erb_template("index.html.erb").result(binding)
       html = html.html_safe if html.respond_to?(:html_safe)
       html
     end
 
+    # Generate an HTML style tag with the CSS for the view.
+    #
+    # @return [String] The HTML style tag with CSS.
     def style_tag
       tag = "<style type=\"text/css\">\n#{css}\n</style>"
       tag = tag.html_safe if tag.respond_to?(:html_safe)
       tag
     end
 
+    # Convert the view to a string by rendering it.
+    #
+    # @return [String] The rendered HTML.
     def to_s
       render
     end

data/lib/ultra_settings/coerce.rb

@@ -93,11 +93,13 @@ module UltraSettings
         time
       end
 
+      # @param value [Object] The value to check.
       # @return [Boolean] true if the value is a numeric type or a string representing a number.
       def numeric?(value)
         value.is_a?(Numeric) || (value.is_a?(String) && value.to_s.match?(NUMERIC_REGEX))
       end
 
+      # @param value [Object] The value to check.
       # @return [Boolean] true if the value is nil or empty.
       def blank?(value)
         return true if value.nil?
@@ -109,6 +111,7 @@ module UltraSettings
         end
       end
 
+      # @param value [Object] The value to check.
       # @return [Boolean] true if the value is not nil and not empty.
       def present?(value)
         !blank?(value)

data/lib/ultra_settings/config_helper.rb

@@ -1,16 +1,20 @@
 # frozen_string_literal: true
 
 module UltraSettings
-  # Helper module for setting up a class to use the config methods
+  # Helper module for setting up a class to use the config methods.
   #
-  # Usage:
-  # class TestClass
-  #   extend UltraSettings::ConfigHelper
-  #   configuration_class TestConfiguration
-  # end
-  # TestClass.config => TestConfiguration.instance
-  # TestClass.new.config => TestConfiguration.instance
+  # @example
+  #   class TestClass
+  #     extend UltraSettings::ConfigHelper
+  #     configuration_class TestConfiguration
+  #   end
+  #   TestClass.config # => TestConfiguration.instance
+  #   TestClass.new.config # => TestConfiguration.instance
   module ConfigHelper
+    # Define the configuration class and create config methods.
+    #
+    # @param config_class [Class] The configuration class to use.
+    # @return [void]
     def configuration_class(config_class)
       define_singleton_method :config do
         config_class.instance

data/lib/ultra_settings/configuration.rb

@@ -61,7 +61,7 @@ module UltraSettings
           default: default,
           default_if: default_if,
           env_var: construct_env_var(name, env_var),
-          runtime_setting: (static ? nil : construct_runtime_setting(name, runtime_setting)),
+          runtime_setting: construct_runtime_setting(name, runtime_setting),
           yaml_key: construct_yaml_key(name, yaml_key),
           static: static,
           secret: secret

data/lib/ultra_settings/configuration_view.rb

@@ -11,10 +11,17 @@ module UltraSettings
   #  <h1>Service Configuration</h1>
   #  <%= UltraSettings::ConfigurationView.new(ServiceConfiguration.instance).render %>
   class ConfigurationView
+    # Initialize the configuration view with a configuration instance.
+    #
+    # @param configuration [UltraSettings::Configuration] The configuration instance to display.
     def initialize(configuration)
       @configuration = configuration
     end
 
+    # Render the HTML for the configuration view.
+    #
+    # @param table_class [String] CSS class for the table element (maintained for backwards compatibility).
+    # @return [String] The rendered HTML.
     def render(table_class: "")
       configuration = @configuration
       html = ViewHelper.erb_template("configuration.html.erb").result(binding)
@@ -22,6 +29,9 @@ module UltraSettings
       html
     end
 
+    # Convert the view to a string by rendering it.
+    #
+    # @return [String] The rendered HTML.
     def to_s
       render
     end

data/lib/ultra_settings/field.rb

@@ -118,6 +118,7 @@ module UltraSettings
     end
 
     def runtime_setting_value(settings)
+      return nil if static? || (secret? && !UltraSettings.runtime_settings_secure?)
       return nil unless settings && runtime_setting
 
       if type == :array && settings.respond_to?(:array)

data/lib/ultra_settings/rack_app.rb

@@ -5,11 +5,18 @@ 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
+    # Initialize a new Rack application for displaying settings.
+    #
+    # @param color_scheme [Symbol, nil] The color scheme to use in the UI (:light, :dark, or :system).
     def initialize(color_scheme: nil)
       @webview = nil
       @color_scheme = color_scheme
     end
 
+    # Handle Rack requests and return the settings HTML page.
+    #
+    # @param env [Hash] The Rack environment.
+    # @return [Array] A Rack response array [status, headers, body].
     def call(env)
       [200, {"content-type" => "text/html; charset=utf8"}, [webview.render_settings]]
     end

data/lib/ultra_settings/uninitialized_runtime_settings.rb

@@ -3,26 +3,31 @@
 module UltraSettings
   # This class is used to represent runtime settings that have not been initialized yet.
   # You can use this to protect your application from accidentally accessing runtime settings
-  # before they are initialized. Doing this can cquse unexpected behavior if the runtime settings
-  # engine has not yet been initialized. For instance, if your runtime settings enging reads from
+  # before they are initialized. Doing this can cause unexpected behavior if the runtime settings
+  # engine has not yet been initialized. For instance, if your runtime settings engine reads from
   # a database it would not be available until the database connection is established.
   #
-  # The intention of this class is to set it a the runtime settings at the beginning of initialization
+  # The intention of this class is to set it as the runtime settings at the beginning of initialization
   # and then set the actual runtime settings engine after the initialization is complete. It will
   # act as a guard to prevent invalid runtime settings backed configurations from being used during
   # initialization.
   #
   # @example
   #
-  # UltraSettings.runtime_settings = UltraSettings::UninitializedRuntimeSettings
-  # ActiveSupport.on_load(:active_record) do
-  #   UltraSettings.runtime_settings = SuperSettings
-  # end
+  #   UltraSettings.runtime_settings = UltraSettings::UninitializedRuntimeSettings
+  #   ActiveSupport.on_load(:active_record) do
+  #     UltraSettings.runtime_settings = SuperSettings
+  #   end
   class UninitializedRuntimeSettings
     class Error < StandardError
     end
 
     class << self
+      # Raises an error when attempting to access runtime settings during initialization.
+      #
+      # @param key [String] The key being accessed.
+      # @return [void]
+      # @raise [Error] Always raises an error to prevent access during initialization.
       def [](key)
         raise Error.new("Attempt to call runtime setting #{key} during initialization")
       end

data/lib/ultra_settings/view_helper.rb

@@ -6,14 +6,25 @@ module UltraSettings
     @cache = {}
 
     class << self
+      # Get an ERB template for rendering.
+      #
+      # @param path [String] The path to the template file.
+      # @return [ERB] The compiled ERB template.
       def erb_template(path)
         @cache["erb:#{path}"] ||= ERB.new(read_app_file(path))
       end
 
+      # Read a file from the app directory.
+      #
+      # @param path [String] The path to the file relative to the app directory.
+      # @return [String] The contents of the file.
       def read_app_file(path)
         @cache["file:#{path}"] ||= File.read(File.join(app_dir, path))
       end
 
+      # Get the app directory path.
+      #
+      # @return [String] The absolute path to the app directory.
       def app_dir
         File.expand_path(File.join("..", "..", "app"), __dir__)
       end

data/lib/ultra_settings/web_view.rb

@@ -5,18 +5,26 @@ module UltraSettings
   class WebView
     attr_reader :layout_css
 
+    # Initialize a new WebView with the specified color scheme.
+    #
     # @param color_scheme [Symbol] The color scheme to use in the UI. This can be `:light`,
-    #  `:dark`, or `:system`. The default is `:light`.
+    #   `:dark`, or `:system`. The default is `:light`.
     def initialize(color_scheme: :light)
       @color_scheme = (color_scheme || :light).to_sym
       @layout_template = ViewHelper.erb_template("layout.html.erb")
       @layout_css = scheme_layout_css(@color_scheme)
     end
 
+    # Render the complete settings page HTML.
+    #
+    # @return [String] The rendered HTML page.
     def render_settings
       @layout_template.result(binding)
     end
 
+    # Get the content for the settings page.
+    #
+    # @return [String] The HTML content for the settings.
     def content
       UltraSettings::ApplicationView.new(color_scheme: @color_scheme).render
     end

data/lib/ultra_settings/yaml_config.rb

@@ -33,11 +33,18 @@ module UltraSettings
   # In addition, the keys are flattened into a one level deep hash with dots
   # separating the keys.
   class YamlConfig
+    # Initialize a YAML configuration loader.
+    #
+    # @param path [String, Pathname] The path to the YAML configuration file.
+    # @param environment [String] The environment section to load from the YAML file.
     def initialize(path, environment)
       yaml = load_yaml(path)
       @config = environment_config(yaml, environment)
     end
 
+    # Convert the loaded configuration to a hash.
+    #
+    # @return [Hash] The flattened configuration hash.
     def to_h
       @config
     end

data/lib/ultra_settings.rb

@@ -38,6 +38,7 @@ module UltraSettings
   @mutex = Mutex.new
   @runtime_settings = nil
   @runtime_settings_url = nil
+  @runtime_settings_secure = true
 
   class << self
     # Adds a configuration to the root namespace. The configuration will be
@@ -111,6 +112,7 @@ module UltraSettings
     # Defaults to "development".
     #
     # @param value [String] The environment name to use.
+    # @return [void]
     def yaml_config_env=(value)
       Configuration.yaml_config_env = value
     end
@@ -128,6 +130,7 @@ module UltraSettings
     # this is a period.
     #
     # @param value [String] The delimiter to use.
+    # @return [void]
     def runtime_setting_delimiter=(value)
       Configuration.runtime_setting_delimiter = value.to_s
     end
@@ -162,6 +165,9 @@ module UltraSettings
     # Set the object to use for runtime settings. This can be any object that
     # responds to the [] method. If you are using the `super_settings` gem,
     # you can set this to `SuperSettings`.
+    #
+    # @param value [#[]] The object to use for runtime settings.
+    # @return [void]
     attr_writer :runtime_settings
 
     # Get the object to use for runtime settings.
@@ -176,21 +182,46 @@ module UltraSettings
     # URL will be displayed in the web view for fields that support runtime settings.
     # The URL may contain a `${name}` placeholder that will be replaced with the name
     # of the setting.
+    #
+    # @param value [String] The URL for changing runtime settings.
+    # @return [void]
     attr_writer :runtime_settings_url
 
     # Get the URL for changing runtime settings.
     #
     # @param name [String] The name of the setting.
+    # @param type [String] The type of the setting.
+    # @param description [String] The description of the setting.
     # @return [String, nil]
     # @api private
-    def runtime_settings_url(name, type)
+    def runtime_settings_url(name: nil, type: nil, description: nil)
       url = @runtime_settings_url.to_s
       return nil if url.empty?
 
-      url = url.gsub("${name}", URI.encode_www_form_component(name.to_s))
-      url.gsub("${type}", URI.encode_www_form_component(type.to_s))
+      url.gsub("${name}", URI.encode_www_form_component(name.to_s))
+        .gsub("${type}", URI.encode_www_form_component(type.to_s))
+        .gsub("${description}", URI.encode_www_form_component(description.to_s))
+    end
+
+    # Set whether or not the runtime settings engine is considered secure. If this is set
+    # to false, then runtime settings will be disabled for all fields marked as secret.
+    # The default value is true.
+    #
+    # @param value [Boolean] Whether the runtime settings engine is secure.
+    # @return [void]
+    attr_writer :runtime_settings_secure
+
+    # Check if the runtime settings engine is considered secure.
+    #
+    # @return [Boolean]
+    def runtime_settings_secure?
+      @runtime_settings_secure
     end
 
+    # Set whether fields should be considered secret by default.
+    #
+    # @param value [Boolean] Whether fields should be secret by default.
+    # @return [void]
     def fields_secret_by_default=(value)
       Configuration.fields_secret_by_default = value
     end
@@ -245,6 +276,7 @@ module UltraSettings
           unless klass < Configuration
             raise TypeError.new("Configuration class #{class_name} does not inherit from UltraSettings::Configuration")
           end
+
           @configurations[name] = klass
         end
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ultra_settings
 version: !ruby/object:Gem::Version
-  version: 2.6.1
+  version: 2.7.0
 platform: ruby
 authors:
 - Brian Durand
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-05 00:00:00.000000000 Z
+date: 2025-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler