ultra_settings 2.4.4 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05c73bd3709ee539db4def5c1d6f5e86def7fb9704b68ae52faacb4e66eec0a6
-  data.tar.gz: 7dab6438fdd2faac932a1b308be3ea8462369c8f71c0dc9bb796787a51e6c0f7
+  metadata.gz: b07db0c8343574b5e9356dfed5e8752596df84920aa3136945e4fbf9d26c88b7
+  data.tar.gz: 8d8b1a0d5134d9eb7e6d16a873a1c98d506a17e1e458cca704f6bf0f42a75dfb
 SHA512:
-  metadata.gz: 7e303425dd2663cf4237d07263b27085c34e4ddbf8e56cbe6f6acc85edef187f3a74192662aa9264d46f1c2fc9a99154de86e4d01247fd9bc92d8d6757be4c22
-  data.tar.gz: 85fd0209d4ed5d7271fdd5d46c24957130f7f03b42132eaad74270d7c95faa7b8d66090deddd674aa176a2afe0629c48a8a2574ada8df1afae464503598055be
+  metadata.gz: 29414f841f3fb1d365bff0c590b9bbc070e46363aff9efeba31d7d92ff7b5992787d414e923e2b7aca9b767e6e61d9db53b9baccb990779ab0eeb67485d422fd
+  data.tar.gz: 646aa68cfa787a46a447b78f82b4ecbc37c4cf841a2217c426a2610464db735f33e1e5dbdd7441c1e2e9ee329eda194ec875bac726ed8df01ca37eaac9d4d91b

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.5.0
+
+### Added
+
+- Added mechanism for guarding against using runtime settings during initialization with the `UltraSettings::UninitializedRuntimeSettings` class.
+
+### Changed
+
+- Runtime settings will now try to load arrays from runtime settings using the `array` method if it is defined. This provides for better integration with the `super_settings` gem to avoid coercing values to and from strings.
+
+## 2.4.5
+
+### Fixed
+
+- Add check for nil YAML config path to avoid error loading YAML file if the path is not set.
+
 ## 2.4.4
 
 ### Changed

data/README.md

@@ -170,6 +170,8 @@ end
 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.
+
 #### 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.
@@ -178,6 +180,21 @@ There is a companion gem [super_settings](https://github.com/bdurand/super_setti
 UltraSettings.runtime_settings = SuperSettings
 ```
 
+#### Initialization Issues
+
+Runtime settings should not be used during application initialization. Often the values set during initialization are static so it can be misleading to use runtime settings for them. There can also be race conditions where the runtime settings implementation itself needs to be initialized. You can guard against unintended usage of runtime settings during initialization by using the `UltraSettings::UninitializedRuntimeSettings` class. This class will raise an error if you try to access a setting before the runtime settings have been initialized.
+
+```ruby
+# Set the runtime settings to the uninitialized class to raise errors if anything tries to use
+# reference a runtime setting during initializaton.
+UltraSettings.runtime_settings = UltraSettings::UninitializedRuntimeSettings
+
+# Switch to using the super_settings gem after the ActiveRecord has been initialized.
+ActiveSupport.on_load(:active_record) do
+  UltraSettings.runtime_settings = SuperSettings
+end
+```
+
 #### 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.
@@ -261,6 +278,16 @@ While for production, the values would be the combination of `production` and `s
 
 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.
 
+If want to use configuration objects in code that is initialized with the Rails application before initializers are run, then you'll need to setup the configuration manually.
+
+For instance, if you want to create a `DatabaseConfiguration` class that is used in the ERB code in `database.yml`, then you'll need to setup the configuration before the Rails application is initialized in `application.rb`.
+
+```ruby
+UltraSettings.yaml_config_env = Rails.env
+UltraSettings.yaml_config_path = __dir__
+require_relative '../app/configurations/database_configuration'
+```
+
 ### Removing The Hierarchy
 
 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.

data/VERSION

@@ -1 +1 @@
-2.4.4
+2.5.0

data/lib/ultra_settings/configuration.rb

@@ -158,6 +158,9 @@ module UltraSettings
       # @return [Pathname, nil]
       def configuration_file
         unless defined?(@configuration_file)
+          default_file = default_configuration_file
+          return nil if default_file.nil?
+
           @configuration_file = default_configuration_file
         end
         return nil? unless @configuration_file
@@ -383,6 +386,8 @@ module UltraSettings
       end
 
       def default_configuration_file
+        return nil if yaml_config_path.nil?
+
         path = Pathname.new(yaml_config_path)
         path.join(*"#{root_name}.yml".split("/"))
       end

data/lib/ultra_settings/field.rb

@@ -99,7 +99,7 @@ module UltraSettings
       value = env[env_var] if env && env_var
       value = nil if value == ""
       if value.nil?
-        value = settings[runtime_setting] if settings && runtime_setting
+        value = runtime_setting_value(settings)
         value = nil if value == ""
         if value.nil?
           value = yaml_value(yaml_config)
@@ -117,6 +117,18 @@ module UltraSettings
       [value, source]
     end
 
+    def runtime_setting_value(settings)
+      return nil unless settings && runtime_setting
+
+      if type == :array && settings.respond_to?(:array)
+        if settings.method(:array).parameters.count { |ptype, pname| ptype == :req } == 1
+          return settings.array(runtime_setting)
+        end
+      end
+
+      settings[runtime_setting]
+    end
+
     def yaml_value(yaml_config)
       return nil unless yaml_config && yaml_key
 

data/lib/ultra_settings/railtie.rb

@@ -9,6 +9,7 @@ module UltraSettings
     config.ultra_settings = ActiveSupport::OrderedOptions.new
     config.ultra_settings.auto_load_directories ||= [File.join("app", "configurations")]
 
+    # initializer "ultra_settings.before_bootstrap", before: :bootstrap_hook do
     config.before_configuration do
       UltraSettings::Configuration.yaml_config_env ||= Rails.env
       UltraSettings::Configuration.yaml_config_path ||= Rails.root.join("config")

data/lib/ultra_settings/uninitialized_runtime_settings.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+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
+  # 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
+  # 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
+  class UninitializedRuntimeSettings
+    class Error < StandardError
+    end
+
+    class << self
+      def [](key)
+        raise Error.new("Attempt to call runtime setting #{key} during initialization")
+      end
+    end
+  end
+end

data/lib/ultra_settings.rb

@@ -16,6 +16,7 @@ require_relative "ultra_settings/rack_app"
 require_relative "ultra_settings/web_view"
 require_relative "ultra_settings/application_view"
 require_relative "ultra_settings/configuration_view"
+require_relative "ultra_settings/uninitialized_runtime_settings"
 require_relative "ultra_settings/yaml_config"
 require_relative "ultra_settings/version"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ultra_settings
 version: !ruby/object:Gem::Version
-  version: 2.4.4
+  version: 2.5.0
 platform: ruby
 authors:
 - Brian Durand
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-05 00:00:00.000000000 Z
+date: 2025-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,7 @@ files:
 - lib/ultra_settings/field.rb
 - lib/ultra_settings/rack_app.rb
 - lib/ultra_settings/railtie.rb
+- lib/ultra_settings/uninitialized_runtime_settings.rb
 - lib/ultra_settings/version.rb
 - lib/ultra_settings/web_view.rb
 - lib/ultra_settings/yaml_config.rb