super_settings 1.0.1 → 2.0.0

data/lib/super_settings/storage/s3_storage.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "aws-sdk-s3"
+
+module SuperSettings
+  module Storage
+    # Storage backend for storing the settings in an S3 object. This should work with any S3-compatible
+    # storage service.
+    class S3Storage < JSONStorage
+      SETTINGS_FILE = "settings.json"
+      HISTORY_FILE_SUFFIX = ".history.json"
+      DEFAULT_PATH = "super_settings"
+
+      # Configuration for the S3 storage backend.
+      #
+      # * access_key_id - The AWS access key ID. Defaults to the SUPER_SETTINGS_AWS_ACCESS_KEY_ID
+      #   or AWS_ACCESS_KEY_ID environment variable or whatever is set in the `Aws.config` object.
+      # * secret_access_key - The AWS secret access key. Defaults to the SUPER_SETTINGS_AWS_SECRET_ACCESS_KEY
+      #  or AWS_SECRET_ACCESS_KEY environment variable or whatever is set in the `Aws.config` object.
+      # * region - The AWS region. Defaults to the SUPER_SETTINGS_AWS_REGION or AWS_REGION environment variable.
+      #   This is required for AWS S3 but may be optional for S3-compatible services.
+      # * endpoint - The S3 endpoint URL. This is optional and should only be used for S3-compatible services.
+      #   Defaults to the SUPER_SETTINGS_AWS_ENDPOINT or AWS_ENDPOINT environment variable.
+      # * bucket - The S3 bucket name. Defaults to the SUPER_SETTINGS_S3_BUCKET or AWS_S3_BUCKET
+      #   environment variable.
+      # * object - The S3 object key. Defaults to "super_settings.json.gz" or the value set in the
+      #   SUPER_SETTINGS_S3_OBJECT environment variable.
+      #
+      # You can also specify the configuration using a URL in the format using the SUPER_SETTINGS_S3_URL
+      # environment variable. The URL should be in the format:
+      #
+      # ```
+      #   s3://access_key_id:secret_access_key@region/bucket/object
+      # ```
+      class Configuration
+        attr_accessor :access_key_id, :secret_access_key, :region, :endpoint, :bucket
+        attr_reader :path
+
+        def initialize
+          @access_key_id ||= ENV.fetch("SUPER_SETTINGS_AWS_ACCESS_KEY_ID", ENV["AWS_ACCESS_KEY_ID"])
+          @secret_access_key ||= ENV.fetch("SUPER_SETTINGS_AWS_SECRET_ACCESS_KEY", ENV["AWS_SECRET_ACCESS_KEY"])
+          @region ||= ENV.fetch("SUPER_SETTINGS_AWS_REGION", ENV["AWS_REGION"])
+          @endpoint ||= ENV.fetch("SUPER_SETTINGS_AWS_ENDPOINT", ENV["AWS_ENDPOINT"])
+          @bucket ||= ENV.fetch("SUPER_SETTINGS_S3_BUCKET", ENV["AWS_S3_BUCKET"])
+          @path ||= ENV.fetch("SUPER_SETTINGS_S3_OBJECT", DEFAULT_PATH)
+          self.url = ENV["SUPER_SETTINGS_S3_URL"] unless ENV["SUPER_SETTINGS_S3_URL"].to_s.empty?
+        end
+
+        def url=(url)
+          return if url.to_s.empty?
+
+          uri = URI.parse(url)
+          raise ArgumentError, "Invalid S3 URL" unless uri.scheme == "s3"
+
+          self.access_key_id = uri.user if uri.user
+          self.secret_access_key = uri.password if uri.password
+          self.region = uri.host if uri.host
+          _, bucket, path = uri.path.split("/", 3) if uri.path
+          self.bucket = bucket if bucket
+          self.path = path if path
+        end
+
+        def path=(value)
+          @path = "#{value}.chomp('/')/"
+        end
+
+        def hash
+          [self.class, access_key_id, secret_access_key, region, endpoint, bucket, path].hash
+        end
+      end
+
+      @bucket = nil
+      @bucket_hash = nil
+
+      class << self
+        def last_updated_at
+          all.collect(&:updated_at).compact.max
+        end
+
+        def configuration
+          @config ||= Configuration.new
+        end
+
+        def destroy_all
+          s3_bucket.objects(prefix: configuration.path).each do |object|
+            if object.key == file_path(SETTINGS_FILE) || object.key.end_with?(HISTORY_FILE_SUFFIX)
+              object.delete
+            end
+          end
+        end
+
+        protected
+
+        def default_load_asynchronous?
+          true
+        end
+
+        def settings_json_payload
+          object = settings_object
+          return nil unless object.exists?
+
+          object.get.body.read
+        end
+
+        def save_settings_json(json)
+          object = settings_object
+          object.put(body: json)
+        end
+
+        def save_history_json(key, json)
+          object = history_object(key)
+          object.put(body: json)
+        end
+
+        private
+
+        def s3_bucket
+          if configuration.hash != @bucket_hash
+            @bucket_hash = configuration.hash
+            options = {
+              endpoint: configuration.endpoint,
+              access_key_id: configuration.access_key_id,
+              secret_access_key: configuration.secret_access_key,
+              region: configuration.region
+            }
+            options[:force_path_style] = true if configuration.endpoint
+            options.compact!
+
+            @bucket = Aws::S3::Resource.new(options).bucket(configuration.bucket)
+          end
+          @bucket
+        end
+
+        def s3_object(filename)
+          s3_bucket.object(file_path(filename))
+        end
+
+        def file_path(filename)
+          "#{configuration.path}#{filename}"
+        end
+
+        def settings_object
+          s3_object(SETTINGS_FILE)
+        end
+
+        def history_object(key)
+          s3_object("#{key}#{HISTORY_FILE_SUFFIX}")
+        end
+
+        def history_json(key)
+          object = history_object(key)
+          return nil unless object.exists?
+
+          object.get.body.read
+        end
+      end
+
+      protected
+
+      def fetch_history_json
+        self.class.send(:history_json, key)
+      end
+    end
+  end
+end

data/lib/super_settings/storage/storage_attributes.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module SuperSettings
+  module Storage
+    # Generic class that can be extended to represent a setting in memory.
+    class StorageAttributes
+      include SuperSettings::Storage
+
+      attr_reader :key, :raw_value, :description, :value_type, :updated_at, :created_at
+
+      def initialize(attributes = nil)
+        @key = nil
+        @raw_value = nil
+        @description = nil
+        @value_type = nil
+        @deleted = false
+        @updated_at = nil
+        @created_at = nil
+        @persisted = false
+        super
+      end
+
+      def key=(value)
+        @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 updated_at=(value)
+        @updated_at = SuperSettings::Coerce.time(value)
+      end
+
+      def created_at=(value)
+        @created_at = SuperSettings::Coerce.time(value)
+      end
+
+      def deleted?
+        !!@deleted
+      end
+
+      def deleted=(val)
+        @deleted = !!val
+      end
+
+      def persisted?
+        !!@persisted
+      end
+
+      def persisted=(val)
+        @persisted = !!val
+      end
+    end
+  end
+end

data/lib/super_settings/storage/test_storage.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "json"
-
 module SuperSettings
   module Storage
     # Implementation of the SuperSettings::Storage model for running unit tests.
@@ -28,7 +26,7 @@ module SuperSettings
           items
         end
 
-        def clear
+        def destroy_all
           @settings = {}
           @history = {}
         end
@@ -42,7 +40,7 @@ module SuperSettings
         end
 
         def updated_since(time)
-          settings.values.select { |attributes| attributes[:updated_at].to_f >= time.to_f }.collect do |attributes|
+          settings.values.select { |attributes| attributes[:updated_at].to_f > time.to_f }.collect do |attributes|
             setting = new(attributes)
             setting.send(:set_persisted!)
             setting
@@ -54,7 +52,7 @@ module SuperSettings
           return nil unless attributes
           setting = new(attributes)
           setting.send(:set_persisted!)
-          setting
+          setting unless setting.deleted?
         end
 
         def last_updated_at

data/lib/super_settings/storage/transaction.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module SuperSettings
+  module Storage
+    # This module provides support for transactions in storage models that don't natively
+    # support transactions.
+    module Transaction
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def transaction(&block)
+          if Thread.current[transaction_key]
+            yield Thread.current[transaction_key]
+          else
+            begin
+              changes = []
+              Thread.current[transaction_key] = changes
+
+              yield(changes)
+
+              if save_all(changes) != false
+                changes.each do |object|
+                  object.persisted = true if object.respond_to?(:persisted=)
+                end
+              end
+            ensure
+              Thread.current[transaction_key] = nil
+            end
+          end
+        end
+
+        def save_all(changes)
+          # :nocov:
+          raise NotImplementedError
+          # :nocov:
+        end
+
+        private
+
+        def transaction_key
+          "#{name}.transaction"
+        end
+      end
+
+      def persisted=(value)
+        @persisted = Coerce.boolean(value)
+      end
+
+      def persisted?
+        !!@persisted
+      end
+
+      def save!
+        self.updated_at ||= Time.now
+        self.created_at ||= updated_at
+
+        self.class.transaction do |changes|
+          changes << self
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/super_settings/storage.rb

@@ -4,8 +4,15 @@ 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
+    autoload :StorageAttributes, File.join(__dir__, "storage/storage_attributes")
+    autoload :HistoryAttributes, File.join(__dir__, "storage/history_attributes")
+    autoload :Transaction, File.join(__dir__, "storage/transaction")
+    autoload :ActiveRecordStorage, File.join(__dir__, "storage/active_record_storage")
+    autoload :HttpStorage, File.join(__dir__, "storage/http_storage")
+    autoload :RedisStorage, File.join(__dir__, "storage/redis_storage")
+    autoload :JSONStorage, File.join(__dir__, "storage/json_storage")
+    autoload :S3Storage, File.join(__dir__, "storage/s3_storage")
+    autoload :MongoDBStorage, File.join(__dir__, "storage/mongodb_storage")
 
     def self.included(base)
       base.extend(ClassMethods)
@@ -84,6 +91,11 @@ module SuperSettings
       # Set to true to force loading setting asynchronously in a background thread.
       attr_writer :load_asynchronous
 
+      # Implementing classes can override this method to delete all settings. This is used
+      # for testing purposes.
+      def destroy_all
+      end
+
       protected
 
       # Implementing classes can override this method to indicate if it is safe to load the
@@ -151,6 +163,7 @@ module SuperSettings
     end
 
     # The description for the setting.
+    #
     # @return [String]
     def description
       # :nocov:
@@ -159,7 +172,7 @@ module SuperSettings
     end
 
     # Set the description for the setting.
-
+    #
     # @param val [String]
     # @return [void]
     def description=(val)
@@ -269,13 +282,9 @@ module SuperSettings
 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
+  ActiveSupport.on_load(:active_record_base) do
     require_relative "storage/active_record_storage"
   end
-elsif defined?(ActiveRecord::Base)
-  require_relative "storage/active_record_storage"
 end
 # :nocov:

data/lib/super_settings/time_precision.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SuperSettings
+  # Helper class for truncating timestamps to a specific precision. This is used by storage engines
+  # to ensure that timestamps are stored and compared with the same precision.
+  class TimePrecision
+    attr_reader :time
+
+    def initialize(time, precision = :microsecond)
+      raise ArgumentError.new("Invalid precision: #{precision}") unless valid_precision?(precision)
+
+      @time = time_with_precision(time.to_f, precision) if time
+    end
+
+    def to_f
+      @time.to_f
+    end
+
+    private
+
+    def valid_precision?(precision)
+      [:microsecond, :millisecond].include?(precision)
+    end
+
+    def time_with_precision(timestamp, precision)
+      usec = (timestamp % 1) * 1_000_000.0
+      if precision == :millisecond
+        milliseconds = (usec / 1000.0).round(3).floor
+        Time.at(timestamp.to_i, milliseconds, :millisecond).utc
+      else
+        microseconds = usec.round
+        Time.at(timestamp.to_i, microseconds, :microsecond).utc
+      end
+    end
+  end
+end

data/lib/super_settings.rb

@@ -1,26 +1,28 @@
 # frozen_string_literal: true
 
-require_relative "super_settings/application"
+require "json"
+
+# These classes are required for the gem to function.
+require_relative "super_settings/attributes"
 require_relative "super_settings/coerce"
 require_relative "super_settings/configuration"
 require_relative "super_settings/context"
-require_relative "super_settings/context/rack_middleware"
 require_relative "super_settings/local_cache"
-require_relative "super_settings/rest_api"
-require_relative "super_settings/rack_application"
-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
+require_relative "super_settings/time_precision"
 
 # This is the main interface to the access settings.
 module SuperSettings
+  # These classes are autoloaded when they are needed.
+  autoload :Application, "super_settings/application"
+  autoload :RestAPI, "super_settings/rest_api"
+  autoload :RackApplication, "super_settings/rack_application"
+  autoload :ControllerActions, "super_settings/controller_actions"
+  autoload :HistoryItem, "super_settings/history_item"
+  autoload :HttpClient, "super_settings/http_client"
+  autoload :VERSION, "super_settings/version"
+
   DEFAULT_REFRESH_INTERVAL = 5.0
 
   @local_cache = LocalCache.new(refresh_interval: DEFAULT_REFRESH_INTERVAL)
@@ -105,6 +107,28 @@ module SuperSettings
       Array(val).collect { |v| v&.to_s }
     end
 
+    # Get a pseudo random number. This method works the same as Kernel.rand. However, if you are
+    # inside a context block, then the random number will be the same each time you call this method.
+    # This is useful when you need to generate a random number for a setting that you want to remain
+    # constant for the duration of the block.
+    #
+    # So, for instance, if you are generating a random number to determine if a feature is enabled,
+    # you can use this method to ensure that the feature is either always enabled or always disabled
+    # for the duration of the block.
+    #
+    # @param max [Integer, Float, Range] the maximum value or range to use for the random number
+    # @return [Integer, Float] the random number. It will be an integer if max is an integer, otherwise
+    #   it will be a float.
+    def rand(max = nil)
+      max ||= 1.0
+      context = current_context
+      if context
+        context.rand(max)
+      else
+        Random.rand(max)
+      end
+    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.
@@ -148,7 +172,7 @@ module SuperSettings
     def context(&block)
       reset_context = Thread.current[:super_settings_context].nil?
       begin
-        Thread.current[:super_settings_context] ||= {}
+        Thread.current[:super_settings_context] ||= Context::Current.new
         yield
       ensure
         Thread.current[:super_settings_context] = nil if reset_context
@@ -201,6 +225,13 @@ module SuperSettings
       end
     end
 
+    # Return the configuration object.
+    #
+    # @return [SuperSettings::Configuration]
+    def configuration
+      Configuration.instance
+    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
@@ -241,3 +272,7 @@ module SuperSettings
     end
   end
 end
+
+if defined?(Rails::Engine)
+  require_relative "super_settings/engine"
+end

data/super_settings.gemspec

@@ -4,10 +4,17 @@ Gem::Specification.new do |spec|
   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.summary = "SuperSettings provides a scalable framework for managing dynamic runtime application settings with in-memory caching, strong typing, a built-in web UI, and support for multiple storage backends."
+
   spec.homepage = "https://github.com/bdurand/super_settings"
   spec.license = "MIT"
 
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => spec.homepage,
+    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md"
+  }
+
   # 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[
@@ -16,6 +23,8 @@ Gem::Specification.new do |spec|
     Gemfile
     Gemfile.lock
     Rakefile
+    docker-compose.yml
+    config.ru
     assets/
     bin/
     gemfiles/
@@ -29,5 +38,5 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler"
 
-  spec.required_ruby_version = ">= 2.5"
+  spec.required_ruby_version = ">= 2.6"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: super_settings
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Brian Durand
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-11 00:00:00.000000000 Z
+date: 2024-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -32,7 +32,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- MIT-LICENSE
+- MIT-LICENSE.txt
 - README.md
 - VERSION
 - app/helpers/super_settings/settings_helper.rb
@@ -43,40 +43,57 @@ files:
 - lib/super_settings/application.rb
 - lib/super_settings/application/api.js
 - lib/super_settings/application/helper.rb
-- lib/super_settings/application/images/edit.svg
-- lib/super_settings/application/images/info.svg
+- lib/super_settings/application/images/arrow-down-short.svg
+- lib/super_settings/application/images/arrow-up-short.svg
+- lib/super_settings/application/images/info-circle.svg
+- lib/super_settings/application/images/pencil-square.svg
 - lib/super_settings/application/images/plus.svg
-- lib/super_settings/application/images/slash.svg
-- lib/super_settings/application/images/trash.svg
+- lib/super_settings/application/images/trash3.svg
+- lib/super_settings/application/images/x-circle.svg
 - lib/super_settings/application/index.html.erb
 - lib/super_settings/application/layout.html.erb
 - lib/super_settings/application/layout_styles.css
+- lib/super_settings/application/layout_vars.css.erb
 - lib/super_settings/application/scripts.js
+- lib/super_settings/application/style_vars.css.erb
 - lib/super_settings/application/styles.css
 - lib/super_settings/attributes.rb
 - lib/super_settings/coerce.rb
 - lib/super_settings/configuration.rb
 - lib/super_settings/context.rb
+- lib/super_settings/context/current.rb
 - lib/super_settings/context/rack_middleware.rb
 - lib/super_settings/context/sidekiq_middleware.rb
 - lib/super_settings/controller_actions.rb
 - lib/super_settings/engine.rb
 - lib/super_settings/history_item.rb
+- lib/super_settings/http_client.rb
 - lib/super_settings/local_cache.rb
 - lib/super_settings/rack_application.rb
 - lib/super_settings/rest_api.rb
 - lib/super_settings/setting.rb
 - lib/super_settings/storage.rb
 - lib/super_settings/storage/active_record_storage.rb
+- lib/super_settings/storage/active_record_storage/models.rb
+- lib/super_settings/storage/history_attributes.rb
 - lib/super_settings/storage/http_storage.rb
+- lib/super_settings/storage/json_storage.rb
+- lib/super_settings/storage/mongodb_storage.rb
 - lib/super_settings/storage/redis_storage.rb
+- lib/super_settings/storage/s3_storage.rb
+- lib/super_settings/storage/storage_attributes.rb
 - lib/super_settings/storage/test_storage.rb
+- lib/super_settings/storage/transaction.rb
+- lib/super_settings/time_precision.rb
 - lib/super_settings/version.rb
 - super_settings.gemspec
 homepage: https://github.com/bdurand/super_settings
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/bdurand/super_settings
+  source_code_uri: https://github.com/bdurand/super_settings
+  changelog_uri: https://github.com/bdurand/super_settings/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -85,16 +102,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.12
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
-summary: Fast access runtime settings for a Rails application with an included UI
-  and API for administration.
+summary: SuperSettings provides a scalable framework for managing dynamic runtime
+  application settings with in-memory caching, strong typing, a built-in web UI, and
+  support for multiple storage backends.
 test_files: []

data/lib/super_settings/application/images/edit.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-edit"><path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"></path><path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"></path></svg>

data/lib/super_settings/application/images/info.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-info"><circle cx="12" cy="12" r="10"></circle><line x1="12" y1="16" x2="12" y2="12"></line><line x1="12" y1="8" x2="12.01" y2="8"></line></svg>

data/lib/super_settings/application/images/slash.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-slash"><circle cx="12" cy="12" r="10"></circle><line x1="4.93" y1="4.93" x2="19.07" y2="19.07"></line></svg>