ultra_settings 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ff5c5961b5070a9234049d2588bd59150e82d2cf87b46c0686067c6d72dd815
-  data.tar.gz: 8df668372d8f6c7dd4c72ad55a789c8bd854bf0bfa0509a5e4a1da69bc74e93e
+  metadata.gz: a34c970ed06134a778e29f09ef7640a255a82f45bbf74e703963a7d9b911b598
+  data.tar.gz: 8065a6941af25b2d18b0e6617af074443c4de7da24541fad0d062f562a640c4d
 SHA512:
-  metadata.gz: 7734298e87bd1fa4b7649ee5ddc64a0ef50f0e6e439bda7eb2042af055141ad5147ee07187ea53bbafbd5372430674a442f77e8c0277099cc8ff9ad7e1b20429
-  data.tar.gz: 565fc7f9071292490d41a634c1b0c89530cbc065f925d52c3dcc25d8e1009bf8fe45ed84aa809fe6ab150d20d79bd9f90f47524ee2a161dfc9d90fc60ae5fb65
+  metadata.gz: d740cea45e6d52bf0392f9c867661b24b55f01ed0b3bb557f9730876af973d08036a47197539cee655a584a11b07b3ecb7ffcbd51cf4a6032605c9ab59b9277b
+  data.tar.gz: f11544c978f8b17790d9fe50b5fb03338a680da9dd4e045cc6e45cad2ab5e6910b51c737fd2735052eb835232023707dbd93bb6460627376765c01779c1f099f

data/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.2.0
+
+### Added
+
+- Added option for `UltraSettings.runtime_settings_url` to allow configuring a link for editing runtime settings from the web UI.
+
+## 2.1.0
+
+### Added
+
+- Added option to specify the color scheme for the web UI when mounting the rack app to support dark mode.
+
+### Fixed
+
+- Times stored as strings representing the seconds since the epoch are now correctly parsed as Time objects.
+
 ## 2.0.0
 
 ### Fixed

data/README.md

@@ -10,6 +10,24 @@ UltraSettings is a Ruby gem designed for managing application settings from vari
 
 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.
 
+## Table Of Contents
+
+- [Key Features](#key-features)
+- [Usage](#usage)
+  - [Defining Configurations](#defining-configurations)
+  - [Field Options](#field-options)
+  - [Environment Variables](#environment-variables)
+  - [Runtime Settings](#runtime-settings)
+  - [YAML Files](#yaml-files)
+  - [Removing The Hierarchy](#removing-the-hierarchy)
+  - [Accessing Settings](#accessing-settings)
+- [Web UI](#web-ui)
+- [Testing With UltraSettings](#testing-with-ultrasettings)
+- [Rollout Percentages](#rollout-percentages)
+- [Installation](#installation)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Key Features
 
 This gem supports a three-layer hierarchy for defining configuration sources:
@@ -176,6 +194,8 @@ 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 placeholder `${name}` in the URL which will be replaced with the name of the runtime setting. If you are using the `super_settings` gem for runtime settings, then you can target a setting by adding `#edit=${name}` 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.
 
 ### YAML Files
@@ -346,6 +366,12 @@ mount Rack::Builder.new do
 end, at: "/ultra_settings"
 ```
 
+You can specify the color scheme by setting by providing the `color_scheme` option to the `UltraSettings::RackApp` class. The default color scheme is `:light`. You can also set the scheme to `:dark` or `:system`.
+
+```ruby
+UltraSettings::RackApp.new(color_scheme: :dark)
+```
+
 #### 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::ApplicationView` class to render the settings interface within your existing views:
@@ -421,6 +447,25 @@ end
 
 This approach keeps your tests clean and readable while allowing for flexible configuration management during testing.
 
+### Rollout percentages
+
+A common usage of configuration is to control rollout of new features by specifying a percentage value and then testing if a random number is less than it. If you implement this pattern in your configuration, then you should use something like the [consistent_random](https://github.com/bdurand/consistent_random) gem to ensure you are generating consistent values without your units of work.
+
+```ruby
+class MyServiceConfiguration < UltraSettings::Configuration
+  field :use_http2_percentage,
+    type: :float,
+    default: 0.0,
+    description: "Rollout percentage for using the new HTTP/2 driver"
+
+  # Using ConsistentRandom#rand instead of Kernel#rand to ensure that we
+  # get the same result within a request and don't oscillate back and forth
+  # every time we check if this is enabled.
+  def use_http2?
+    ConsistentRandom.new("MyServiceConfiguration.use_http2").rand < use_http2_percentage
+  end
+end
+```
 
 ## Installation
 
@@ -446,6 +491,24 @@ Open a pull request on [GitHub](https://github.com/bdurand/ultra_settings).
 
 Please use the [standardrb](https://github.com/testdouble/standard) syntax and lint your code with `standardrb --fix` before submitting.
 
+You can start a local rack server to test the web UI by running
+
+```bash
+bundle exec rackup
+```
+
+You can test with some setting set by setting environment variable used in the test configuration.
+
+```bash
+MY_SERVICE_HOST=host.example.com MY_SERVICE_TOKEN=secret bundle exec rackup
+```
+
+You can test dark mode by setting the `COLOR_SCHEME` environment variable.
+
+```bash
+COLOR_SCHEME=dark bundle exec rackup
+```
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/VERSION

@@ -1 +1 @@
-2.0.0
+2.2.0

data/app/application.css

@@ -15,29 +15,30 @@
 
 .ultra-settings-table thead th {
   vertical-align: bottom;
-  border-bottom: 2px solid #dee2e6;
+  border-bottom: 2px solid var(--table-border-color);
+  background-color: var(--table-header-bg-color);
 }
 
 .ultra-settings-table td, .ultra-settings-table th {
   padding: 0.75rem;
   vertical-align: top;
-  border-top: 1px solid #dee2e6;
+  border-top: 1px solid var(--table-border-color);
 }
 
 .ultra-settings-table tbody tr:nth-of-type(odd) {
-  background-color: rgba(0, 0, 0, .03);
+  background-color: var(--alt-row-color);
 }
 
 .ultra-settings-table code {
   font-family: monospace;
   font-size: 0.9rem;
   display: inline;
-  color: darkred;
+  color: var(--code-color);
   font-weight: 600;
 }
 
 .ultra-settings-table em {
-  color: gray;
+  color: var(--em-color);
   font-style: italic;
   font-size: 0.9rem;
 }
@@ -49,13 +50,13 @@
   font-size: 1rem;
   font-weight: 400;
   line-height: 1.5;
-  color: #212529;
-  background-color: #fff;
+  color: var(--form-control-color);
+  background-color: var(--form-control-bg-color);
   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: 1px solid var(--form-control-border-color);
   border-radius: .25rem;
   transition: border-color .15s ease-in-out,box-shadow .15s ease-in-out;
   -webkit-appearance: none;

data/app/application_vars.css.erb

@@ -0,0 +1,31 @@
+<% unless color_scheme == :dark %>
+  .ultra-settings-configuration {
+    --table-header-bg-color: #fff;
+    --table-border-color: #dee2e6;
+    --alt-row-color: rgba(0, 0, 0, .05);
+    --form-control-color: #495057;
+    --form-control-bg-color: #fff;
+    --form-control-border-color: #ced4da;
+    --code-color: darkred;
+    --em-color: gray;
+  }
+<% end %>
+
+<% if color_scheme == :system %>
+  @media (prefers-color-scheme: dark) {
+<% end %>
+<% if color_scheme == :system || color_scheme == :dark %>
+  .ultra-settings-configuration {
+    --table-header-bg-color: #333;
+    --table-border-color: #555;
+    --alt-row-color: rgba(0, 0, 0, .30);
+    --form-control-color: #eee;
+    --form-control-bg-color: #666;
+    --form-control-border-color: #555;
+    --code-color: pink;
+    --em-color: #999;
+  }
+<% end %>
+<% if color_scheme == :system %>
+  }
+<% end %>

data/app/configuration.html.erb

@@ -20,7 +20,7 @@
         <th>Notes</th>
       </tr>
     </thead>
-    <tbody>
+    <tbody translate="no">
       <% configuration.class.fields.each do |field| %>
         <% source = configuration.__source__(field.name) %>
         <tr>
@@ -52,14 +52,14 @@
             <% end %>
           </td>
 
-          <td>
+          <td style="word-wrap: break-word;">
             <% 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;">
+            <ul style="margin: 0 0 0 1rem; padding: 0; list-style-type: disc; list-style-position: outside;">
               <% if field.env_var && !configuration.class.environment_variables_disabled? %>
                 <li>
                   <% if source == :env %>
@@ -68,9 +68,8 @@
                   <% else %>
                     Can be
                   <% end %>
-                  set with the
+                  set with the environment variable
                   <code><%= show_defined_value(field.env_var, configuration.__value_from_source__(field.name, :env), field.secret?) %></code>
-                  environment variable.
                   <% if source == :env %>
                     </strong>
                   <% end %>
@@ -84,12 +83,21 @@
                   <% else %>
                     Can be
                   <% end %>
-                  set with the
+                  set with the runtime setting
                   <code><%= show_defined_value(field.runtime_setting, configuration.__value_from_source__(field.name, :settings), field.secret?) %></code>
-                  runtime setting.
                   <% if source == :settings %>
                     </strong>
                   <% end %>
+
+                  <% edit_url = UltraSettings.runtime_settings_url(field.runtime_setting) %>
+                  <% if edit_url %>
+                    <a href="<%= html_escape(edit_url) %>" title="Edit <%= html_escape(field.runtime_setting) %>" style="text-decoration: none; color: inherit; vertical-align: middle;">
+                      <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-pencil-square" viewBox="0 0 16 16">
+                        <path d="M15.502 1.94a.5.5 0 0 1 0 .706L14.459 3.69l-2-2L13.502.646a.5.5 0 0 1 .707 0l1.293 1.293zm-1.75 2.456-2-2L4.939 9.21a.5.5 0 0 0-.121.196l-.805 2.414a.25.25 0 0 0 .316.316l2.414-.805a.5.5 0 0 0 .196-.12l6.813-6.814z"/>
+                        <path fill-rule="evenodd" d="M1 13.5A1.5 1.5 0 0 0 2.5 15h11a1.5 1.5 0 0 0 1.5-1.5v-6a.5.5 0 0 0-1 0v6a.5.5 0 0 1-.5.5h-11a.5.5 0 0 1-.5-.5v-11a.5.5 0 0 1 .5-.5H9a.5.5 0 0 0 0-1H2.5A1.5 1.5 0 0 0 1 2.5z"/>
+                      </svg>
+                    </a>
+                  <% end %>
                 </li>
               <% end %>
               <% if field.yaml_key && !configuration.class.yaml_config_disabled? %>
@@ -100,9 +108,8 @@
                   <% else %>
                     Can be
                   <% end %>
-                  set with the
+                  set with the configuration file key
                   <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 %>

data/app/layout.css

@@ -1,12 +1,14 @@
-* {box-sizing:border-box;}
+* {
+  box-sizing:border-box;
+}
 
 body {
   font-family: sans-serif;
   font-size: 1rem;
   line-height: 1.5;
   text-align: left;
-  color: #212529;
-  background-color: #ffffff;
+  color: var(--text-color);
+  background-color: var(--background-color);
   margin: 0;
   padding: 0;
 }

data/app/layout.html.erb

@@ -5,6 +5,7 @@
     <title>Application Configuration</title>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="format-detection" content="telephone=no email=no date=no address=no">
     <style type="text/css">
       <%= @layout_css %>
       <%= css %>

data/app/layout_vars.css.erb

@@ -0,0 +1,19 @@
+<% unless color_scheme != :dark %>
+  :root {
+    --text-color: #212529;
+    --background-color: #ffffff;
+  }
+<% end %>
+
+<% if color_scheme == :system %>
+  @media (prefers-color-scheme: dark) {
+<% end %>
+<% if color_scheme == :system || color_scheme == :dark %>
+  :root {
+    --text-color: #fff;
+    --background-color: #333;
+  }
+<% end %>
+<% if color_scheme == :system %>
+  }
+<% end %>

data/lib/ultra_settings/coerce.rb

@@ -18,6 +18,8 @@ module UltraSettings
     ]).freeze
     # rubocop:enable Lint/BooleanSymbol
 
+    NUMERIC_REGEX = /\A-?\d+(?:\.\d+)?\z/
+
     class << self
       # Cast a value to a specific type.
       #
@@ -33,13 +35,19 @@ module UltraSettings
         when :float
           value.is_a?(Float) ? value : value.to_s&.to_f
         when :boolean
-          Coerce.boolean(value)
+          boolean(value)
         when :datetime
-          Coerce.time(value)
+          time(value)
         when :array
           Array(value).map(&:to_s)
         when :symbol
           value.to_s.to_sym
+        when :rollout
+          if numeric?(value)
+            value.to_f
+          else
+            boolean(value)
+          end
         else
           value.to_s
         end
@@ -50,13 +58,9 @@ module UltraSettings
       # @param value [Object]
       # @return [Boolean]
       def boolean(value)
-        if value == false
-          false
-        elsif blank?(value)
-          nil
-        else
-          !FALSE_VALUES.include?(value)
-        end
+        return nil if blank?(value)
+
+        !FALSE_VALUES.include?(value)
       end
 
       # Cast a value to a Time object.
@@ -66,8 +70,9 @@ module UltraSettings
       def time(value)
         value = nil if value.nil? || value.to_s.empty?
         return nil if value.nil?
-        time = if value.is_a?(Numeric)
-          Time.at(value)
+
+        time = if numeric?(value)
+          Time.at(value.to_f)
         elsif value.respond_to?(:to_time)
           value.to_time
         else
@@ -79,9 +84,15 @@ module UltraSettings
         time
       end
 
+      # @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
+
       # @return [Boolean] true if the value is nil or empty.
       def blank?(value)
         return true if value.nil?
+
         if value.respond_to?(:empty?)
           value.empty?
         else

data/lib/ultra_settings/configuration.rb

@@ -7,6 +7,9 @@ module UltraSettings
     ALLOWED_NAME_PATTERN = /\A[a-z_][a-zA-Z0-9_]*\z/
     ALLOWED_TYPES = [:string, :symbol, :integer, :float, :boolean, :datetime, :array].freeze
 
+    @env_var_prefix = nil
+    @runtime_setting_prefix = nil
+
     class << self
       # Define a field on the configuration. This will create a getter method for the field.
       # The field value will be read from the environment, runtime settings, or a YAML file
@@ -64,7 +67,7 @@ module UltraSettings
           secret: secret
         )
 
-        class_eval <<-RUBY, __FILE__, __LINE__ + 1 # rubocop:disable Security/Eval
+        class_eval <<~RUBY, __FILE__, __LINE__ + 1 # rubocop:disable Security/Eval
           def #{name}
             __get_value__(#{name.inspect})
           end
@@ -435,10 +438,10 @@ module UltraSettings
     end
 
     def initialize
-      @mutex = Mutex.new
-      @memoized_values = {}
-      @override_values = {}
-      @yaml_config = nil
+      @ultra_settings_mutex = Mutex.new
+      @ultra_settings_memoized_values = {}
+      @ultra_settings_override_values = {}
+      @ultra_settings_yaml_config = nil
     end
 
     def [](name)
@@ -450,7 +453,7 @@ module UltraSettings
     end
 
     def override!(values, &block)
-      save_val = @override_values[Thread.current.object_id]
+      save_val = @ultra_settings_override_values[Thread.current.object_id]
 
       temp_values = (save_val || {}).dup
       values.each do |key, value|
@@ -458,13 +461,13 @@ module UltraSettings
       end
 
       begin
-        @mutex.synchronize do
-          @override_values[Thread.current.object_id] = temp_values
+        @ultra_settings_mutex.synchronize do
+          @ultra_settings_override_values[Thread.current.object_id] = temp_values
         end
         yield
       ensure
-        @mutex.synchronize do
-          @override_values[Thread.current.object_id] = save_val
+        @ultra_settings_mutex.synchronize do
+          @ultra_settings_override_values[Thread.current.object_id] = save_val
         end
       end
     end
@@ -530,12 +533,12 @@ module UltraSettings
       field = self.class.send(:defined_fields)[name]
       return nil unless field
 
-      if field.static? && @memoized_values.include?(name)
-        return @memoized_values[name]
+      if field.static? && @ultra_settings_memoized_values.include?(name)
+        return @ultra_settings_memoized_values[name]
       end
 
-      if @override_values[Thread.current.object_id]&.include?(name)
-        value = field.coerce(@override_values[Thread.current.object_id][name])
+      if @ultra_settings_override_values[Thread.current.object_id]&.include?(name)
+        value = field.coerce(@ultra_settings_override_values[Thread.current.object_id][name])
       else
         env = ENV if field.env_var
         settings = UltraSettings.__runtime_settings__ if field.runtime_setting
@@ -549,11 +552,11 @@ module UltraSettings
       end
 
       if field.static?
-        @mutex.synchronize do
-          if @memoized_values.include?(name)
-            value = @memoized_values[name]
+        @ultra_settings_mutex.synchronize do
+          if @ultra_settings_memoized_values.include?(name)
+            value = @ultra_settings_memoized_values[name]
           else
-            @memoized_values[name] = value
+            @ultra_settings_memoized_values[name] = value
           end
         end
       end
@@ -578,7 +581,7 @@ module UltraSettings
     end
 
     def __yaml_config__
-      @yaml_config ||= self.class.load_yaml_config || {}
+      @ultra_settings_yaml_config ||= self.class.load_yaml_config || {}
     end
   end
 end

data/lib/ultra_settings/rack_app.rb

@@ -5,8 +5,9 @@ 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
+    def initialize(color_scheme: nil)
       @webview = nil
+      @color_scheme = color_scheme
     end
 
     def call(env)
@@ -19,7 +20,7 @@ module UltraSettings
       if ENV.fetch("RAILS_ENV", ENV.fetch("RACK_ENV", "development")) == "development"
         @webview = nil
       end
-      @webview ||= WebView.new
+      @webview ||= WebView.new(color_scheme: @color_scheme)
     end
   end
 end

data/lib/ultra_settings/web_view.rb

@@ -5,10 +5,13 @@ module UltraSettings
   class WebView
     attr_reader :css
 
-    def initialize
+    # @param color_scheme [Symbol] The color scheme to use in the UI. This can be `:light`,
+    #  `:dark`, or `:system`. The default is `:light`.
+    def initialize(color_scheme: :light)
+      color_scheme = (color_scheme || :light).to_sym
       @layout_template = erb_template("layout.html.erb")
-      @layout_css = read_app_file("layout.css")
-      @css = read_app_file("application.css")
+      @layout_css = layout_css(color_scheme)
+      @css = application_css(color_scheme)
     end
 
     def render_settings
@@ -32,5 +35,17 @@ module UltraSettings
     def app_dir
       File.expand_path(File.join("..", "..", "app"), __dir__)
     end
+
+    def layout_css(color_scheme)
+      vars = erb_template("layout_vars.css.erb").result(binding)
+      css = read_app_file("layout.css")
+      "#{vars}\n#{css}"
+    end
+
+    def application_css(color_scheme)
+      vars = erb_template("application_vars.css.erb").result(binding)
+      css = read_app_file("application.css")
+      "#{vars}\n#{css}"
+    end
   end
 end

data/lib/ultra_settings.rb

@@ -6,6 +6,7 @@ require "time"
 require "pathname"
 require "singleton"
 require "digest"
+require "uri"
 
 require_relative "ultra_settings/configuration"
 require_relative "ultra_settings/coerce"
@@ -33,6 +34,7 @@ module UltraSettings
   @configurations = {}
   @mutex = Mutex.new
   @runtime_settings = nil
+  @runtime_settings_url = nil
 
   class << self
     # Adds a configuration to the root namespace. The configuration will be
@@ -167,6 +169,24 @@ module UltraSettings
       @runtime_settings
     end
 
+    # Set the URL for changing runtime settings. If this is set, then a link to the
+    # 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.
+    attr_writer :runtime_settings_url
+
+    # Get the URL for changing runtime settings.
+    #
+    # @param name [String] The name of the setting.
+    # @return [String, nil]
+    # @api private
+    def runtime_settings_url(name)
+      url = @runtime_settings_url.to_s
+      return nil if url.empty?
+
+      url.gsub("${name}", URI.encode_www_form_component(name))
+    end
+
     def fields_secret_by_default=(value)
       Configuration.fields_secret_by_default = value
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ultra_settings
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Brian Durand
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-28 00:00:00.000000000 Z
+date: 2024-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -37,10 +37,12 @@ files:
 - VERSION
 - app/application.css
 - app/application.js
+- app/application_vars.css.erb
 - app/configuration.html.erb
 - app/index.html.erb
 - app/layout.css
 - app/layout.html.erb
+- app/layout_vars.css.erb
 - lib/ultra_settings.rb
 - lib/ultra_settings/application_view.rb
 - lib/ultra_settings/coerce.rb