super_settings 0.0.0.rc1

data/lib/super_settings/storage/test_storage.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "json"
+
+# :nocov:
+module SuperSettings
+  module Storage
+    # Implementation of the SuperSettings::Storage model for running unit tests.
+    class TestStorage
+      include Storage
+
+      attr_reader :key, :raw_value, :description, :value_type, :updated_at, :created_at
+      attr_accessor :changed_by
+
+      class << self
+        def settings
+          @settings ||= {}
+        end
+
+        def history(key)
+          @history ||= {}
+          items = @history[key]
+          unless items
+            items = []
+            @history[key] = items
+          end
+          items
+        end
+
+        def clear
+          @settings = {}
+          @history = {}
+        end
+
+        def all
+          settings.values.collect do |attributes|
+            setting = new(attributes)
+            setting.send(:set_persisted!)
+            setting
+          end
+        end
+
+        def updated_since(time)
+          settings.values.select { |attributes| attributes[:updated_at].to_f >= time.to_f }.collect do |attributes|
+            setting = new(attributes)
+            setting.send(:set_persisted!)
+            setting
+          end
+        end
+
+        def find_by_key(key)
+          attributes = settings[key]
+          return nil unless attributes
+          setting = new(attributes)
+          setting.send(:set_persisted!)
+          setting
+        end
+
+        def last_updated_at
+          settings.values.collect { |attributes| attributes[:updated_at] }.max
+        end
+
+        protected
+
+        def default_load_asynchronous?
+          true
+        end
+      end
+
+      def history(limit: nil, offset: 0)
+        items = self.class.history(key)
+        items[offset, limit || items.length].collect do |attributes|
+          HistoryItem.new(attributes)
+        end
+      end
+
+      def create_history(changed_by:, created_at:, value: nil, deleted: false)
+        item = {key: key, value: value, deleted: deleted, changed_by: changed_by, created_at: created_at}
+        self.class.history(key).unshift(item)
+      end
+
+      def save!
+        self.updated_at ||= Time.now
+        self.created_at ||= updated_at
+        if defined?(@original_key) && @original_key
+          self.class.settings.delete(@original_key)
+        end
+        self.class.settings[key] = attributes
+        set_persisted!
+        true
+      end
+
+      def key=(value)
+        @original_key ||= key
+        @key = (Coerce.blank?(value) ? nil : value.to_s)
+      end
+
+      def raw_value=(value)
+        @raw_value = (Coerce.blank?(value) ? nil : value.to_s)
+      end
+
+      def value_type=(value)
+        @value_type = (Coerce.blank?(value) ? nil : value.to_s)
+      end
+
+      def description=(value)
+        @description = (Coerce.blank?(value) ? nil : value.to_s)
+      end
+
+      def deleted=(value)
+        @deleted = Coerce.boolean(value)
+      end
+
+      def created_at=(value)
+        @created_at = SuperSettings::Coerce.time(value)
+      end
+
+      def updated_at=(value)
+        @updated_at = SuperSettings::Coerce.time(value)
+      end
+
+      def deleted?
+        !!(defined?(@deleted) && @deleted)
+      end
+
+      def persisted?
+        !!(defined?(@persisted) && @persisted)
+      end
+
+      protected
+
+      def redact_history!
+        self.class.history(key).each do |item|
+          item[:value] = nil
+        end
+      end
+
+      private
+
+      def set_persisted!
+        @persisted = true
+      end
+
+      def attributes
+        {
+          key: key,
+          raw_value: raw_value,
+          value_type: value_type,
+          description: description,
+          deleted: deleted?,
+          updated_at: updated_at,
+          created_at: created_at
+        }
+      end
+    end
+  end
+end
+# :nocov:

data/lib/super_settings/storage.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module SuperSettings
+  # Abstraction over how a setting is stored and retrieved from the storage engine. Models
+  # must implement the methods module in this module that raise `NotImplementedError`.
+  module Storage
+    class RecordInvalid < StandardError
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.include(Attributes) unless base.instance_methods.include?(:attributes=)
+    end
+
+    module ClassMethods
+      # Storage classes must implent this method to return all settings included deleted ones.
+      # @return [Array<SuperSetting::Setting::Storage>]
+      def all
+        # :nocov:
+        raise NotImplementedError
+        # :nocov:
+      end
+
+      # Return all non-deleted settings.
+      # @return [Array<SuperSetting::Setting::Storage>]
+      def active
+        all.reject(&:deleted?)
+      end
+
+      # Storage classes must implement this method to return all settings updates since the
+      # specified timestamp.
+      # @return [Array<SuperSetting::Setting::Storage>]
+      def updated_since(timestamp)
+        # :nocov:
+        raise NotImplementedError
+        # :nocov:
+      end
+
+      # Storage classes must implement this method to return a settings by it's key.
+      # @return [SuperSetting::Setting::Storage]
+      def find_by_key(key)
+        # :nocov:
+        raise NotImplementedError
+        # :nocov:
+      end
+
+      # Storage classes must implement this method to return most recent time that any
+      # setting was updated.
+      # @return [Time]
+      def last_updated_at
+        # :nocov:
+        raise NotImplementedError
+        # :nocov:
+      end
+
+      # Implementing classes can override this method to setup a thread safe connection within a block.
+      def with_connection(&block)
+        yield
+      end
+
+      # Implementing classes can override this method to wrap an operation in an atomic transaction.
+      def transaction(&block)
+        yield
+      end
+
+      # @return [Boolean] true if it's safe to load setting asynchronously in a background thread.
+      def load_asynchronous?
+        !!(defined?(@load_asynchronous) && !@load_asynchronous.nil? ? @load_asynchronous : default_load_asynchronous?)
+      end
+
+      # Set to true to force loading setting asynchronously in a background thread.
+      attr_writer :load_asynchronous
+
+      protected
+
+      # Implementing classes can override this method to indicate if it is safe to load the
+      # setting in a separate thread.
+      def default_load_asynchronous?
+        false
+      end
+    end
+
+    # @return [String] the key for the setting
+    def key
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # Set the key for the setting.
+    # @param val [String]
+    # @return [void]
+    def key=(val)
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # @return [String] the raw value for the setting before it is type cast.
+    def raw_value
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # Set the raw value for the setting.
+    # @param val [String]
+    # @return [void]
+    def raw_value=(val)
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # @return [String] the value type for the setting
+    def value_type
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # Set the value type for the setting.
+    # @param val [String] one of string, integer, float, boolean, datetime, array, or secret
+    # @return [void]
+    def value_type=(val)
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # @return [String] the description for the setting
+    def description
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # Set the description for the setting.
+    # @param val [String]
+    # @return [void]
+    def description=(val)
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # @return [Boolean] true if the setting marked as deleted
+    def deleted?
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # Set the deleted flag for the setting. Settings should not actually be deleted since
+    # the record is needed to keep the local cache up to date.
+    # @param val [Boolean]
+    # @return [void]
+    def deleted=(val)
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # @return [Time] the time the setting was last updated
+    def updated_at
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # Set the last updated time for the setting.
+    # @param val [Time]
+    # @return [void]
+    def updated_at=(val)
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # @return [Time] the time the setting was created
+    def created_at
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # Set the created time for the setting.
+    # @param val [Time]
+    # @return [void]
+    def created_at=(val)
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # Return array of history items reflecting changes made to the setting over time. Items
+    # should be returned in reverse chronological order so that the most recent changes are first.
+    # @return [Array<SuperSettings::History>]
+    def history(limit: nil, offset: 0)
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # Create a history item for the setting
+    def create_history(changed_by:, created_at:, value: nil, deleted: false)
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # Persist the record to storage.
+    # @return [void]
+    def save!
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    # @return [Boolean] true if the record has been stored.
+    def persisted?
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.key == key
+    end
+
+    protected
+
+    # Remove the value stored on history records if the setting is changed to a secret since
+    # these are not stored encrypted in the database. Implementing classes must redefine this
+    # method.
+    def redact_history!
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+  end
+end
+
+# :nocov:
+require_relative "storage/http_storage"
+require_relative "storage/redis_storage"
+if defined?(ActiveSupport) && ActiveSupport.respond_to?(:on_load)
+  ActiveSupport.on_load(:active_record) do
+    require_relative "storage/active_record_storage"
+  end
+elsif defined?(ActiveRecord::Base)
+  require_relative "storage/active_record_storage"
+end
+# :nocov:

data/lib/super_settings/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SuperSettings
+  VERSION = File.read(File.expand_path("../../VERSION", __dir__)).chomp
+end

data/lib/super_settings.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "secret_keys"
+
+require_relative "super_settings/application"
+require_relative "super_settings/coerce"
+require_relative "super_settings/configuration"
+require_relative "super_settings/local_cache"
+require_relative "super_settings/encryption"
+require_relative "super_settings/rest_api"
+require_relative "super_settings/rack_middleware"
+require_relative "super_settings/controller_actions"
+require_relative "super_settings/attributes"
+require_relative "super_settings/setting"
+require_relative "super_settings/history_item"
+require_relative "super_settings/storage"
+require_relative "super_settings/version"
+
+if defined?(Rails::Engine)
+  require_relative "super_settings/engine"
+end
+
+# This is the main interface to the access settings.
+module SuperSettings
+  DEFAULT_REFRESH_INTERVAL = 5.0
+
+  class << self
+    # Get a setting value cast to a string.
+    #
+    # @param key [String, Symbol]
+    # @param default [String] value to return if the setting value is nil
+    # @return [String]
+    def get(key, default = nil)
+      val = local_cache[key]
+      val.nil? ? default : val.to_s
+    end
+
+    # Get a setting value cast to an integer.
+    #
+    # @param key [String, Symbol]
+    # @param default [Integer] value to return if the setting value is nil
+    # @return [Integer]
+    def integer(key, default = nil)
+      val = local_cache[key]
+      (val.nil? ? default : val)&.to_i
+    end
+
+    # Get a setting value cast to a float.
+    #
+    # @param key [String, Symbol]
+    # @param default [Numeric] value to return if the setting value is nil
+    # @return [Float]
+    def float(key, default = nil)
+      val = local_cache[key]
+      (val.nil? ? default : val)&.to_f
+    end
+
+    # Get a setting value cast to a boolean.
+    #
+    # @param key [String, Symbol]
+    # @param default [Boolean] value to return if the setting value is nil
+    # @return [Boolean]
+    def enabled?(key, default = false)
+      val = local_cache[key]
+      Coerce.boolean(val.nil? ? default : val)
+    end
+
+    # Get a setting value cast to a Time.
+    #
+    # @param key [String, Symbol]
+    # @param default [Time] value to return if the setting value is nil
+    # @return [Time]
+    def datetime(key, default = nil)
+      val = local_cache[key]
+      Coerce.time(val.nil? ? default : val)
+    end
+
+    # Get a setting value cast to an array of strings.
+    #
+    # @param key [String, Symbol]
+    # @param default [Array] value to return if the setting value is nil
+    # @return [Array]
+    def array(key, default = nil)
+      val = local_cache[key]
+      val = default if val.nil?
+      return nil if val.nil?
+      Array(val).collect { |v| v&.to_s }
+    end
+
+    # Get setting values cast to a hash. This method can be used to cast the flat setting key/value
+    # store into a structured data store. It uses a delimiter to define how keys are nested which
+    # defaults to a dot.
+    #
+    # If, for example, you have three keys in you settings "A.B1.C1 = 1", "A.B1.C2 = 2", and "A.B2.C3 = 3", the
+    # nested structure will be:
+    #
+    # `{"A" => {"B1" => {"C1" => 1, "C2" => 2}, "B2" => {"C3" => 3}}}`
+    #
+    # This whole hash would be returned if you called `hash` without any key. If you called it with the
+    # key "A.B1", it would return `{"C1" => 1, "C2" => 2}`.
+    #
+    # @param key [String, Symbol] the prefix patter to fetch keys for; default to returning all settings
+    # @param default [Hash] value to return if the setting value is nil
+    # @param delimiter [String] the delimiter to use to define nested keys in the hash; defaults to "."
+    # @return [Hash]
+    def structured(key = nil, default = nil, delimiter: ".", max_depth: nil)
+      value = local_cache.structured(key, delimiter: delimiter, max_depth: max_depth)
+      return (default || {}) if value.empty?
+      value
+    end
+
+    # Create settings and update the local cache with the values. If a block is given, then the
+    # value will be reverted at the end of the block. This method can be used in tests when you
+    # need to inject a specific value into your settings.
+    #
+    # @param key [String, Symbol] the key to set
+    # @param value [Object] the value to set
+    # @param value_type [String, Symbol] the value type to set; if the setting does not already exist,
+    #   this will be inferred from the value.
+    # @return [void]
+    def set(key, value, value_type: nil)
+      setting = Setting.find_by_key(key)
+      if setting
+        setting.value_type = value_type if value_type
+      else
+        setting = Setting.new(key: key)
+        setting.value_type = (value_type || Setting.value_type(value) || Setting::STRING)
+      end
+      previous_value = setting.value
+      setting.value = value
+      begin
+        setting.save!
+        local_cache.load_settings unless local_cache.loaded?
+        local_cache.update_setting(setting)
+        if block_given?
+          yield
+        end
+      ensure
+        if block_given?
+          setting.value = previous_value
+          setting.save!
+          local_cache.load_settings unless local_cache.loaded?
+          local_cache.update_setting(setting)
+        end
+      end
+    end
+
+    # Load the settings from the database into the in memory cache.
+    def load_settings
+      local_cache.load_settings
+      local_cache.wait_for_load
+      nil
+    end
+
+    # Force refresh the settings in the in memory cache to be in sync with the database.
+    def refresh_settings
+      local_cache.refresh
+      nil
+    end
+
+    # Reset the in memory cache. The cache will be automatically reloaded the next time
+    # you access a setting.
+    def clear_cache
+      local_cache.reset
+      nil
+    end
+
+    # Return true if the in memory cache has been loaded from the database.
+    #
+    # @return [Boolean]
+    def loaded?
+      local_cache.loaded?
+    end
+
+    # Configure various aspects of the gem. The block will be yielded to with a configuration
+    # object. You should use this method to configure the gem from an Rails initializer since
+    # it will handle ensuring all the appropriate frameworks are loaded first.
+    #
+    # yieldparam config [SuperSettings::Configuration]
+    def configure(&block)
+      Configuration.instance.defer(&block)
+      unless defined?(Rails::Engine)
+        Configuration.instance.call
+      end
+    end
+
+    # Set the number of seconds between checks to synchronize the in memory cache from the database.
+    # This setting aids in performance since it throttles the number of times the database is queried
+    # for changes. However, changes made to the settings in the databae will take up to the number of
+    # seconds in the refresh interval to be updated in the cache.
+    def refresh_interval=(value)
+      local_cache.refresh_interval = value
+    end
+
+    # Set the secret used to encrypt secret settings in the database.
+    #
+    # If you need to roll your secret, you can pass in an array of values. The first one
+    # specified will be used to encrypt values, but all of the keys will be tried when
+    # decrypting a value already stored in the database.
+    #
+    # @param value [String, Array]
+    def secret=(value)
+      Encryption.secret = value
+      load_settings if loaded?
+    end
+
+    private
+
+    def local_cache
+      @local_cache ||= LocalCache.new(refresh_interval: DEFAULT_REFRESH_INTERVAL)
+    end
+  end
+end

data/lib/tasks/super_settings.rake

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+namespace :super_settings do
+  desc "Encrypt settings marked as secret" do
+    SuperSettings::Setting.where(value_type: "secret").each do |setting|
+      setting.raw_value_will_change! if setting.value
+    end
+  end
+end

data/super_settings.gemspec

@@ -0,0 +1,35 @@
+Gem::Specification.new do |spec|
+  spec.name = "super_settings"
+  spec.version = File.read(File.expand_path("../VERSION", __FILE__)).strip
+  spec.authors = ["Brian Durand"]
+  spec.email = ["bbdurand@gmail.com"]
+
+  spec.summary = "Fast access runtime settings for a Rails application with an included UI and API for administration."
+  spec.homepage = "https://github.com/bdurand/super_settings"
+  spec.license = "MIT"
+
+  # 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[
+    .
+    Appraisals
+    Gemfile
+    Gemfile.lock
+    Rakefile
+    bin/
+    gemfiles/
+    spec/
+    web_ui.png
+  ]
+  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| ignore_files.any? { |path| f.start_with?(path) } }
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "secret_keys", ">= 1.0"
+
+  spec.add_development_dependency "bundler"
+
+  spec.required_ruby_version = ">= 2.5"
+end