process_settings 0.8.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c35c37914363571825848c95ec6d1f3d15811b11b0bea5671f28744a4108129
-  data.tar.gz: 6c252be7fb7d924f50fd9a6cdbbb35bcfa292da595cb79c3e644a8f9f3da08d1
+  metadata.gz: 7ace753f727c3aea91291d906951ff86da6750d6aa4b0db1022ad6155dce42dc
+  data.tar.gz: 1081a5ba75c69f17f6ad308125a748751d381b7289b27e63a0e9130fd96db0bd
 SHA512:
-  metadata.gz: f07d59b5f034ce85b5e20b117fe731d3b3860b6422c0ba2c8fcdaf4c39d88c5af70ed6636952cd9385c25ad9e320cfd1784671689406dae71ac051fdf1daa709
-  data.tar.gz: 3a74f7e775d7c4688a20b0c3b93918992ef5acd3163aa581f411b87fa326ef7cc0eaea0f090915464f3b20f45740112c681543b3a7c8c5c58eba3dca8b0ba6f2
+  metadata.gz: dbfbe4d945aa9d67b02862be7f5905afd36b0c0c1c5fd1f2054d6b263f6ccdaf878bbc6521361c4454183c9d00f882947572933aa6c52850a8c10e3b32839510
+  data.tar.gz: 6e2341fca852024f9d0a518159c6367264376fb760d3efde1904546cc75a40042272ad1c0c9e075b7e68f23891c5812911253f98a66f514f72992aad2324dd7b

data/README.md

@@ -5,6 +5,10 @@ Settings are managed in a git repo, in separate YAML files for each concern (for
 
 The context can be either static to the process (for example, `service_name` or `datacenter`) or dynamic (for example, the current web request `domain`).
 
+## Dependencies
+* Ruby >= 2.6
+* ActiveSupport >= 4.2, < 7
+
 ## Installation
 To install this gem directly on your machine from rubygems, run the following:
 ```ruby
@@ -160,18 +164,56 @@ This will be applied in any process that has (`service_name == "frontend"` OR `s
 The settings YAML files are always combined in alphabetical order by file path. Later settings take precedence over the earlier ones.
 
 ### Testing
-For testing, it is often necessary to set a specific hash for the process_settings values to use in that test case.
-The `ProcessSettings::Testing::MonitorStub` class is provided for this purpose. It can be initialized with a hash and assigned to `ProcessSettings::Monitor.instance`. After the test runs, make sure to call `clear_instance`.
-Note that it has no `targeting` or `settings` keys; it is stubbing the resulting settings hash _after_ targeting has been applied.
-Here is an example using `rspec` conventions:
-```
-before do
-  settings = { "honeypot" => { "answer_odds" => 100 } }
-  ProcessSettings::Monitor.instance = ProcessSettings::Testing::MonitorStub.new(settings)
+For testing, it is often necessary to set a specific override hash for the process_settings values to use in
+that use case.  The `ProcessSettings::Testing::Helpers` module is provided for this purpose.  It can be used to
+override a specific hash of process settings, while leving the rest in tact, and resetting back to the defaults
+after the test case is over.  Here are some examples using various testing frameworks:
+
+#### RSpec
+##### `spec_helper.rb`
+```ruby
+require 'process_settings/testing/helpers'
+
+RSpec.configure do |config|
+  # ...
+
+  include ProcessSettings::Testing::Helpers
+
+  after do
+   reset_process_settings
+  end
+
+  # ...
+end
+```
+
+##### `process_settings_spec.rb`
+```ruby
+require 'spec_helper'
+
+RSpec.describe SomeClass do
+  before do
+    stub_process_settings(honeypot: { answer_odds: 100 })
+  end
+
+  # ...
 end
+```
+
+#### Test::Unit / Minitest
+```ruby
+require 'process_settings/testing/helpers'
+
+context SomeClass do
+  setup do
+    stub_process_settings(honeypot: { answer_odds: 100 })
+  end
+
+  teardown do
+    reset_process_settings
+  end
 
-after do
-  ProcessSettings::Monitor.clear_instance
+  # ...
 end
 ```
 

data/lib/process_settings/abstract_monitor.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'active_support'
+
+require 'process_settings/targeted_settings'
+require 'process_settings/hash_path'
+
+module ProcessSettings
+  class SettingsPathNotFound < StandardError; end
+
+  OnChangeDeprecation = ActiveSupport::Deprecation.new('1.0', 'ProcessSettings::Monitor')
+
+  class AbstractMonitor
+    attr_reader :min_polling_seconds, :logger
+    attr_reader :static_context, :statically_targeted_settings
+
+    def initialize(logger:)
+      @logger = logger
+      @on_change_callbacks = []
+      @when_updated_blocks = Set.new
+      @static_context = {}
+    end
+
+    # This is the main entry point for looking up settings on the Monitor instance.
+    #
+    # @example
+    #
+    # ['path', 'to', 'setting']
+    #
+    # will return 42 in this example settings YAML:
+    # +code+
+    #   path:
+    #     to:
+    #       setting:
+    #         42
+    # +code+
+    #
+    # @param [Array(String)] path The path of one or more strings.
+    #
+    # @param [Hash] dynamic_context Optional dynamic context hash. It will be merged with the static context.
+    #
+    # @param [boolean] required If true (default) will raise `SettingsPathNotFound` if not found; otherwise returns `nil` if not found.
+    #
+    # @return setting value
+    def [](*path, dynamic_context: {}, required: true)
+      targeted_value(*path, dynamic_context: dynamic_context, required: required)
+    end
+
+    # Idempotently adds the given block to the when_updated collection
+    # calls the block first unless initial_update: false is passed
+    # returns a handle (the block itself) which can later be passed into cancel_when_updated
+    def when_updated(initial_update: true, &block)
+      if @when_updated_blocks.add?(block)
+        if initial_update
+          begin
+            block.call(self)
+          rescue => ex
+            logger.error("ProcessSettings::Monitor#when_updated rescued exception during initialization:\n#{ex.class}: #{ex.message}")
+          end
+        end
+      end
+
+      block
+    end
+
+    # removes the given when_updated block identified by the handle returned from when_updated
+    def cancel_when_updated(handle)
+      @when_updated_blocks.delete_if { |callback| callback.eql?(handle) }
+    end
+
+    # Registers the given callback block to be called when settings change.
+    # These are run using the shared thread that monitors for changes so be courteous and don't monopolize it!
+    # @deprecated
+    def on_change(&callback)
+      @on_change_callbacks << callback
+    end
+    deprecate on_change: :when_updated, deprecator: OnChangeDeprecation
+
+    # Assigns a new static context. Recomputes statically_targeted_settings.
+    # Keys must be strings or integers. No symbols.
+    def static_context=(context)
+      self.class.ensure_no_symbols(context)
+
+      @static_context = context
+
+      load_statically_targeted_settings(force_retarget: true)
+    end
+
+    # Returns the process settings value at the given `path` using the given `dynamic_context`.
+    # (It is assumed that the static context was already set through static_context=.)
+    # If nothing set at the given `path`:
+    #   if required, raises SettingsPathNotFound
+    #   else returns nil
+    def targeted_value(*path, dynamic_context:, required: true)
+      # Merging the static context in is necessary to make sure that the static context isn't shifting
+      # this can be rather costly to do every time if the dynamic context is not changing
+      # TODO: Warn in the case where dynamic context was attempting to change a static value
+      # TODO: Cache the last used dynamic context as a potential optimization to avoid unnecessary deep merges
+      # TECH-4402 was created to address these todos
+      full_context = dynamic_context.deep_merge(static_context)
+      result = statically_targeted_settings.reduce(:not_found) do |latest_result, target_and_settings|
+        # find last value from matching targets
+        if target_and_settings.target.target_key_matches?(full_context)
+          if (value = target_and_settings.settings.json_doc.mine(*path, not_found_value: :not_found)) != :not_found
+            latest_result = value
+          end
+        end
+        latest_result
+      end
+
+      if result == :not_found
+        if required
+          raise SettingsPathNotFound, "no settings found for path #{path.inspect}"
+        else
+          nil
+        end
+      else
+        result
+      end
+    end
+
+    private
+
+    class << self
+      def ensure_no_symbols(value)
+        case value
+        when Symbol
+          raise ArgumentError, "symbol value #{value.inspect} found--should be String"
+        when Hash
+          value.each do |k, v|
+            k.is_a?(Symbol) and raise ArgumentError, "symbol key #{k.inspect} found--should be String"
+            ensure_no_symbols(v)
+          end
+        when Array
+          value.each { |v| ensure_no_symbols(v) }
+        end
+      end
+    end
+
+    # Calls all registered on_change callbacks. Rescues any exceptions they may raise.
+    # Note: this method can be re-entrant to the class; the on_change callbacks may call right back into these methods.
+    # Therefore it's critical to finish all transitions and release any resources before calling this method.
+    def notify_on_change
+      @on_change_callbacks.each do |callback|
+        begin
+          callback.call(self)
+        rescue => ex
+          logger.error("ProcessSettings::Monitor#notify_on_change rescued exception:\n#{ex.class}: #{ex.message}")
+        end
+      end
+    end
+
+    def call_when_updated_blocks
+      @when_updated_blocks.each do |block|
+        begin
+          block.call(self)
+        rescue => ex
+          logger.error("ProcessSettings::Monitor#call_when_updated_blocks rescued exception:\n#{ex.class}: #{ex.message}")
+        end
+      end
+    end
+  end
+end

data/lib/process_settings/file_monitor.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'listen'
+require 'psych'
+
+require 'process_settings/abstract_monitor'
+require 'process_settings/targeted_settings'
+require 'process_settings/hash_path'
+
+module ProcessSettings
+  class FileMonitor < AbstractMonitor
+    attr_reader :file_path, :untargeted_settings
+
+    def initialize(file_path, logger:)
+      super(logger: logger)
+
+      @file_path = File.expand_path(file_path)
+      @last_statically_targetted_settings = nil
+      @untargeted_settings = nil
+      @last_untargetted_settings = nil
+
+      start
+    end
+
+    # starts listening for changes
+    # Note: This method creates a new thread that will be monitoring for changes
+    #       do to the nature of how the Listen gem works, there is no record of
+    #       existing threads, calling this mutliple times will result in spinning off
+    #       multiple listen threads and will have unknow effects
+    def start
+      path = File.dirname(file_path)
+
+      # to eliminate any race condition:
+      # 1. set up file watcher
+      # 2. start it (this should trigger if any changes have been made since (1))
+      # 3. load the file
+
+      @listener = file_change_notifier.to(path) do |modified, added, _removed|
+        if modified.include?(file_path) || added.include?(file_path)
+          logger.info("ProcessSettings::Monitor file #{file_path} changed. Reloading.")
+          load_untargeted_settings
+
+          load_statically_targeted_settings
+        end
+      end
+
+      unless ENV['DISABLE_LISTEN_CHANGE_MONITORING']
+        @listener.start
+      end
+
+      load_untargeted_settings
+      load_statically_targeted_settings
+    end
+
+    # stops listening for changes
+    def stop
+      @listener&.stop
+    end
+
+    private
+
+    # Loads the most recent settings from disk
+    def load_untargeted_settings
+      new_untargeted_settings = load_file(file_path)
+      old_version = @untargeted_settings&.version
+      new_version = new_untargeted_settings.version
+      @untargeted_settings = new_untargeted_settings
+      logger.info("ProcessSettings::Monitor#load_untargeted_settings loaded version #{new_version}#{" to replace version #{old_version}" if old_version}")
+    end
+
+    # Loads the latest untargeted settings from disk. Returns the current process settings as a TargetAndProcessSettings given
+    # by applying the static context to the current untargeted settings from disk.
+    # If these have changed, borrows this thread to call notify_on_change and call_when_updated_blocks.
+    def load_statically_targeted_settings(force_retarget: false)
+      if force_retarget || @last_untargetted_settings != @untargeted_settings
+        @last_untargetted_settings = @untargeted_settings
+        @statically_targeted_settings = @untargeted_settings.with_static_context(@static_context)
+        if @last_statically_targetted_settings != @statically_targeted_settings
+          @last_statically_targetted_settings = @statically_targeted_settings
+
+          notify_on_change
+          call_when_updated_blocks
+        end
+      end
+    end
+
+    def load_file(file_path)
+      TargetedSettings.from_file(file_path)
+    end
+
+    def file_change_notifier
+      Listen
+    end
+  end
+end

data/lib/process_settings/monitor.rb

@@ -1,264 +1,53 @@
 # frozen_string_literal: true
 
-require_relative 'targeted_settings'
-require_relative 'hash_path'
-require 'psych'
-require 'listen'
 require 'active_support'
+require 'active_support/deprecation'
 
-module ProcessSettings
-  class SettingsPathNotFound < StandardError; end
-
-  OnChangeDeprecation = ActiveSupport::Deprecation.new('1.0', 'ProcessSettings::Monitor')
-
-  class Monitor
-    attr_reader :file_path, :min_polling_seconds, :logger
-    attr_reader :static_context, :untargeted_settings, :statically_targeted_settings
-
-    DEFAULT_MIN_POLLING_SECONDS = 5
-
-    def initialize(file_path, logger:)
-      @file_path = File.expand_path(file_path)
-      @logger = logger
-      @on_change_callbacks = []
-      @when_updated_blocks = Set.new
-      @static_context = {}
-      @last_statically_targetted_settings = nil
-      @untargeted_settings = nil
-      @last_untargetted_settings = nil
-      @last_untargetted_settings = nil
-
-      start
-    end
-
-    # []
-    #
-    # This is the main entry point for looking up settings on the Monitor instance.
-    #
-    # @example
-    #
-    # ['path', 'to', 'setting']
-    #
-    # will return 42 in this example settings YAML:
-    # +code+
-    #   path:
-    #     to:
-    #       setting:
-    #         42
-    # +code+
-    #
-    # @param [Array(String)] path The path of one or more strings.
-    #
-    # @param [Hash] dynamic_context Optional dynamic context hash. It will be merged with the static context.
-    #
-    # @param [boolean] required If true (default) will raise `SettingsPathNotFound` if not found; otherwise returns `nil` if not found.
-    #
-    # @return setting value
-    def [](*path, dynamic_context: {}, required: true)
-      targeted_value(*path, dynamic_context: dynamic_context, required: required)
-    end
-
-    # starts listening for changes
-    # Note: This method creates a new thread that will be monitoring for changes
-    #       do to the nature of how the Listen gem works, there is no record of
-    #       existing threads, calling this mutliple times will result in spinning off
-    #       multiple listen threads and will have unknow effects
-    def start
-      path = File.dirname(@file_path)
-
-      # to eliminate any race condition:
-      # 1. set up file watcher
-      # 2. start it (this should trigger if any changes have been made since (1))
-      # 3. load the file
-
-      @listener = file_change_notifier.to(path) do |modified, added, _removed|
-        if modified.include?(@file_path) || added.include?(@file_path)
-          @logger.info("ProcessSettings::Monitor file #{@file_path} changed. Reloading.")
-          load_untargeted_settings
-
-          load_statically_targeted_settings
-        end
-      end
-
-      unless ENV['DISABLE_LISTEN_CHANGE_MONITORING']
-        @listener.start
-      end
-
-      load_untargeted_settings
-      load_statically_targeted_settings
-    end
-
-    # stops listening for changes
-    def stop
-      @listener&.stop
-    end
-
-    # Idempotently adds the given block to the when_updated collection
-    # calls the block first unless initial_update: false is passed
-    # returns a handle (the block itself) which can later be passed into cancel_when_updated
-    def when_updated(initial_update: true, &block)
-      if @when_updated_blocks.add?(block)
-        if initial_update
-          begin
-            block.call(self)
-          rescue => ex
-            logger.error("ProcessSettings::Monitor#when_updated rescued exception during initialization:\n#{ex.class}: #{ex.message}")
-          end
-        end
-      end
-
-      block
-    end
-
-    # removes the given when_updated block identified by the handle returned from when_updated
-    def cancel_when_updated(handle)
-      @when_updated_blocks.delete_if { |callback| callback.eql?(handle) }
-    end
-
-    # Registers the given callback block to be called when settings change.
-    # These are run using the shared thread that monitors for changes so be courteous and don't monopolize it!
-    # @deprecated
-    def on_change(&callback)
-      @on_change_callbacks << callback
-    end
-    deprecate on_change: :when_updated, deprecator: OnChangeDeprecation
+require_relative 'file_monitor'
 
-    # Assigns a new static context. Recomputes statically_targeted_settings.
-    # Keys must be strings or integers. No symbols.
-    def static_context=(context)
-      self.class.ensure_no_symbols(context)
-
-      @static_context = context
-
-      load_statically_targeted_settings(force_retarget: true)
-    end
+module ProcessSettings
+  # DEPRECATED
+  class Monitor < FileMonitor
+    class << self
+      attr_reader :logger, :file_path
+      attr_writer :instance
 
-    # Returns the process settings value at the given `path` using the given `dynamic_context`.
-    # (It is assumed that the static context was already set through static_context=.)
-    # If nothing set at the given `path`:
-    #   if required, raises SettingsPathNotFound
-    #   else returns nil
-    def targeted_value(*path, dynamic_context:, required: true)
-      # Merging the static context in is necessary to make sure that the static context isn't shifting
-      # this can be rather costly to do every time if the dynamic context is not changing
-      # TODO: Warn in the case where dynamic context was attempting to change a static value
-      # TODO: Cache the last used dynamic context as a potential optimization to avoid unnecessary deep merges
-      # TECH-4402 was created to address these todos
-      full_context = dynamic_context.deep_merge(static_context)
-      result = statically_targeted_settings.reduce(:not_found) do |latest_result, target_and_settings|
-        # find last value from matching targets
-        if target_and_settings.target.target_key_matches?(full_context)
-          if (value = target_and_settings.settings.json_doc.mine(*path, not_found_value: :not_found)) != :not_found
-            latest_result = value
-          end
-        end
-        latest_result
-      end
+      def file_path=(new_file_path)
+        ActiveSupport::Deprecation.warn("ProcessSettings::Monitor.file_path= is deprecated and will be removed in v1.0.")
+        clear_instance
 
-      if result == :not_found
-        if required
-          raise SettingsPathNotFound, "no settings found for path #{path.inspect}"
-        else
-          nil
-        end
-      else
-        result
+        @file_path = new_file_path
       end
-    end
-
-    private
-
-    # Loads the most recent settings from disk
-    def load_untargeted_settings
-      new_untargeted_settings = load_file(file_path)
-      old_version = @untargeted_settings&.version
-      new_version = new_untargeted_settings.version
-      @untargeted_settings = new_untargeted_settings
-      logger.info("ProcessSettings::Monitor#load_untargeted_settings loaded version #{new_version}#{" to replace version #{old_version}" if old_version}")
-    end
 
-    # Loads the latest untargeted settings from disk. Returns the current process settings as a TargetAndProcessSettings given
-    # by applying the static context to the current untargeted settings from disk.
-    # If these have changed, borrows this thread to call notify_on_change and call_when_updated_blocks.
-    def load_statically_targeted_settings(force_retarget: false)
-      if force_retarget || @last_untargetted_settings != @untargeted_settings
-        @last_untargetted_settings = @untargeted_settings
-        @statically_targeted_settings = @untargeted_settings.with_static_context(@static_context)
-        if @last_statically_targetted_settings != @statically_targeted_settings
-          @last_statically_targetted_settings = @statically_targeted_settings
-
-          notify_on_change
-          call_when_updated_blocks
-        end
+      def new_from_settings
+        file_path or raise ArgumentError, "#{self}::file_path must be set before calling instance method"
+        logger or raise ArgumentError, "#{self}::logger must be set before calling instance method"
+        new(file_path, logger: logger)
       end
-    end
-
-    class << self
-      attr_accessor :file_path
-      attr_reader :logger
-      attr_writer :instance
 
       def clear_instance
         @instance = nil
+        @default_instance = nil
       end
 
       def instance
-        @instance ||= begin
-                        file_path or raise ArgumentError, "#{self}::file_path must be set before calling instance method"
-                        logger or raise ArgumentError, "#{self}::logger must be set before calling instance method"
-                        new(file_path, logger: logger)
-                      end
+        ActiveSupport::Deprecation.warn("ProcessSettings::Monitor.instance is deprecated and will be removed in v1.0. Use ProcessSettings.instance instead.")
+        @instance ||= default_instance
+      end
+
+      def default_instance
+        @default_instance ||= new_from_settings
       end
 
       def logger=(new_logger)
+        ActiveSupport::Deprecation.warn("ProcessSettings::Monitor.logger is deprecated and will be removed in v1.0.")
         @logger = new_logger
         Listen.logger ||= new_logger
       end
 
-      def ensure_no_symbols(value)
-        case value
-        when Symbol
-          raise ArgumentError, "symbol value #{value.inspect} found--should be String"
-        when Hash
-          value.each do |k, v|
-            k.is_a?(Symbol) and raise ArgumentError, "symbol key #{k.inspect} found--should be String"
-            ensure_no_symbols(v)
-          end
-        when Array
-          value.each { |v| ensure_no_symbols(v) }
-        end
-      end
-    end
-
-    # Calls all registered on_change callbacks. Rescues any exceptions they may raise.
-    # Note: this method can be re-entrant to the class; the on_change callbacks may call right back into these methods.
-    # Therefore it's critical to finish all transitions and release any resources before calling this method.
-    def notify_on_change
-      @on_change_callbacks.each do |callback|
-        begin
-          callback.call(self)
-        rescue => ex
-          logger.error("ProcessSettings::Monitor#notify_on_change rescued exception:\n#{ex.class}: #{ex.message}")
-        end
-      end
-    end
-
-    def call_when_updated_blocks
-      @when_updated_blocks.each do |block|
-        begin
-          block.call(self)
-        rescue => ex
-          logger.error("ProcessSettings::Monitor#call_when_updated_blocks rescued exception:\n#{ex.class}: #{ex.message}")
-        end
-      end
+      deprecate :logger, :logger=, :file_path, :file_path=, deprecator: ActiveSupport::Deprecation.new('1.0', 'ProcessSettings')
     end
 
-    def load_file(file_path)
-      TargetedSettings.from_file(file_path)
-    end
-
-    def file_change_notifier
-      Listen
-    end
+    deprecate :initialize, deprecator: ActiveSupport::Deprecation.new('1.0', 'ProcessSettings')
   end
 end

data/lib/process_settings/settings.rb

@@ -11,6 +11,8 @@ module ProcessSettings
     def initialize(json_doc)
       json_doc.is_a?(Hash) or raise ArgumentError, "ProcessSettings must be a Hash; got #{json_doc.inspect}"
 
+      AbstractMonitor.ensure_no_symbols(json_doc)
+
       @json_doc = HashWithHashPath[json_doc]
     end
 

data/lib/process_settings/target.rb

@@ -4,6 +4,8 @@ module ProcessSettings
   class Target
     include Comparable
 
+    TRUE_JSON_DOC = {}.freeze
+
     attr_reader :json_doc
 
     def initialize(json_doc)
@@ -11,7 +13,7 @@ module ProcessSettings
     end
 
     def target_key_matches?(context_hash)
-      @json_doc == {} || self.class.target_key_matches?(@json_doc, context_hash)
+      @json_doc == TRUE_JSON_DOC || self.class.target_key_matches?(@json_doc, context_hash)
     end
 
     def with_static_context(static_context_hash)
@@ -93,5 +95,11 @@ module ProcessSettings
         end
       end
     end
+
+    class << self
+      def true_target
+        @true_target || new(TRUE_JSON_DOC)
+      end
+    end
   end
 end

data/lib/process_settings/target_and_settings.rb

@@ -11,10 +11,10 @@ module ProcessSettings
     def initialize(filename, target, settings)
       @filename = filename
 
-      target.is_a?(Target) or raise ArgumentError, "target must be a ProcessTarget; got #{target.inspect}"
+      target.is_a?(Target) or raise ArgumentError, "target must be a Target; got #{target.inspect}"
       @target = target
 
-      settings.is_a?(Settings) or raise ArgumentError, "settings must be a ProcessSettings; got #{settings.inspect}"
+      settings.is_a?(Settings) or raise ArgumentError, "settings must be a Settings; got #{settings.inspect}"
       @settings = settings
     end
 

data/lib/process_settings/testing/helpers.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'process_settings/monitor'
+require 'process_settings/settings'
+require 'process_settings/target_and_settings'
+
+require 'process_settings/testing/monitor'
+
+module ProcessSettings
+  module Testing
+    module Helpers
+
+      # Adds the given settings_hash as an override at the end of the process_settings array, with default targeting (true).
+      # Therefore this will override these settings while leaving others alone.
+      #
+      # @param [Hash] settings_hash
+      #
+      # @return none
+      def stub_process_settings(settings_hash)
+        new_target_and_settings = ProcessSettings::TargetAndSettings.new(
+          '<test_override>',
+          Target::true_target,
+          ProcessSettings::Settings.new(settings_hash.deep_stringify_keys)
+        )
+
+        new_process_settings = [
+          *initial_instance.statically_targeted_settings,
+          new_target_and_settings
+        ]
+
+        ProcessSettings.instance = ProcessSettings::Testing::Monitor.new(
+          new_process_settings,
+          logger: initial_instance.logger
+        )
+      end
+
+      private
+
+      def initial_instance
+        @initial_instance ||= ProcessSettings.instance
+      end
+    end
+  end
+end

data/lib/process_settings/testing/monitor.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext'
+require 'process_settings/abstract_monitor'
+
+module ProcessSettings
+  module Testing
+
+    # A special instance of the monitor specifically used for testing that
+    # allows the providing of a settings array from memory to initialize
+    # the ProcessSetting Monitor for testing
+    #
+    # @param Array settings_array
+    # @param Logger logger
+    class Monitor < ::ProcessSettings::AbstractMonitor
+      def initialize(settings_array, logger:)
+        super(logger: logger)
+        @statically_targeted_settings = settings_array
+      end
+
+      private
+
+      def load_statically_targetted_settings(force_retarget: false)
+        @statically_targeted_settings
+      end
+    end
+  end
+end

data/lib/process_settings/testing/monitor_stub.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'active_support/core_ext'
+
 require_relative '../monitor'
 require_relative '../hash_with_hash_path'
 
@@ -8,6 +10,7 @@ module ProcessSettings
     # This class implements the Monitor#targeted_value interface but is stubbed to use a simple hash in tests
     class MonitorStub
       def initialize(settings_hash)
+        ActiveSupport::Deprecation.warn("ProcessSettings::Testing::MonitorStub is deprecated and will be removed in future versions. Use ProcessSettings::Testing::Monitor instead.", caller)
         @settings_hash = HashWithHashPath[settings_hash]
       end
 

data/lib/process_settings/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ProcessSettings
-  VERSION = '0.8.2'
+  VERSION = '0.9.0'
 end

data/lib/process_settings.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'active_support'
+require 'active_support/deprecation'
+
 module ProcessSettings
 end
 
@@ -7,8 +10,28 @@ require 'process_settings/monitor'
 
 module ProcessSettings
   class << self
-    # []
+    # Setter method for assigning the monitor instance for ProcessSettings to use
+    #
+    # @example
+    #
+    # ProcessSettings.instance = ProcessSettings::FileMonitor.new(...)
     #
+    # @param [ProcessSettings::AbstractMonitor] monitor The monitor to assign for use by ProcessSettings
+    def instance=(monitor)
+      if monitor && !monitor.is_a?(ProcessSettings::AbstractMonitor)
+        raise ArgumentError, "Invalid monitor of type #{monitor.class.name} provided. Must be of type ProcessSettings::AbstractMonitor"
+      end
+
+      @instance = monitor
+    end
+
+    # Getter method for retrieving the current monitor instance being used by ProcessSettings
+    #
+    # @return [ProcessSettings::AbstractMonitor]
+    def instance
+      @instance ||= lazy_create_instance
+    end
+
     # This is the main entry point for looking up settings in the process.
     #
     # @example
@@ -31,7 +54,14 @@ module ProcessSettings
     #
     # @return setting value
     def [](*path, dynamic_context: {}, required: true)
-      Monitor.instance[*path, dynamic_context: dynamic_context, required: required]
+      instance[*path, dynamic_context: dynamic_context, required: required]
+    end
+
+    private
+
+    def lazy_create_instance
+      ActiveSupport::Deprecation.warn("lazy creation of Monitor instance is deprecated and will be removed from ProcessSettings 1.0")
+      Monitor.instance
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: process_settings
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.9.0
 platform: ruby
 authors:
 - Invoca
@@ -16,14 +16,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '4.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '4.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -70,6 +76,8 @@ files:
 - bin/process_settings_for_services
 - bin/process_settings_version
 - lib/process_settings.rb
+- lib/process_settings/abstract_monitor.rb
+- lib/process_settings/file_monitor.rb
 - lib/process_settings/hash_path.rb
 - lib/process_settings/hash_with_hash_path.rb
 - lib/process_settings/monitor.rb
@@ -78,6 +86,8 @@ files:
 - lib/process_settings/target.rb
 - lib/process_settings/target_and_settings.rb
 - lib/process_settings/targeted_settings.rb
+- lib/process_settings/testing/helpers.rb
+- lib/process_settings/testing/monitor.rb
 - lib/process_settings/testing/monitor_stub.rb
 - lib/process_settings/util.rb
 - lib/process_settings/version.rb