super_settings 0.0.0.rc1

data/lib/super_settings/local_cache.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+module SuperSettings
+  # Cache that stores the settings in memory so they can be looked up without any
+  # network overhead. All of the settings will be loaded in the cache and the database
+  # will only be checked every few seconds for changes so that lookups are very fast.
+  #
+  # The cache is thread safe and it ensures that only a single thread will ever be
+  # trying to update the cache at a time to avoid any dog piling effects.
+  class LocalCache
+    # @private
+    NOT_DEFINED = Object.new.freeze
+    private_constant :NOT_DEFINED
+
+    # @private
+    DRIFT_FACTOR = 10
+    private_constant :DRIFT_FACTOR
+
+    # Number of seconds that the cache will be considered fresh. The database will only be
+    # checked for changed settings at most this often.
+    attr_reader :refresh_interval
+
+    # @parem refresh_interval [Numeric] number of seconds to wait between checking for setting updates
+    def initialize(refresh_interval:)
+      @refresh_interval = refresh_interval
+      @lock = Mutex.new
+      reset
+    end
+
+    # Get a setting value from the cache.
+    #
+    # This method will periodically check the cache for freshness and update the cache from
+    # the database if there are any differences.
+    #
+    # Cache misses will be stored in the cache so that a request for a missing setting does not
+    # hit the database every time. This does mean that that you should not call this method with
+    # a large number of dynamically generated keys since that could lead to memory bloat.
+    #
+    # @param key [String, Symbol] setting key
+    def [](key)
+      ensure_cache_up_to_date!
+      key = key.to_s
+      value = @cache[key]
+
+      if value.nil? && !@cache.include?(key)
+        if @refreshing
+          value = NOT_DEFINED
+        else
+          setting = Setting.find_by_key(key)
+          value = (setting ? setting.value : NOT_DEFINED)
+          # Guard against caching too many cache missees; at some point it's better to slam
+          # the database rather than run out of memory.
+          if setting || @cache.size < 100_000
+            @lock.synchronize do
+              # For case where one thread could be iterating over the cache while it's updated causing an error
+              @cache = @cache.merge(key => value).freeze
+              @hashes = {}
+            end
+          end
+        end
+      end
+
+      return nil if value == NOT_DEFINED
+      value
+    end
+
+    # Return the setting as structured data. The keys will be split by the specified delimiter
+    # to create a nested hash (i.e. "a.b.c" = 1 becomes `{"a" => {"b" => {"c" => 1}}}`).
+    #
+    # See SuperSettings.structured for more details.
+    def structured(key = nil, delimiter: ".", max_depth: nil)
+      key = key.to_s
+      cache_key = [key, delimiter, max_depth]
+      cached_value = @hashes[cache_key]
+      return cached_value if cached_value
+
+      flattened = to_h
+      root_key = ""
+      if Coerce.present?(key)
+        root_key = "#{key}#{delimiter}"
+        reduced_hash = {}
+        flattened.each do |k, v|
+          if k.start_with?(root_key)
+            reduced_hash[k[root_key.length, k.length]] = v
+          end
+        end
+        flattened = reduced_hash
+      end
+
+      structured_hash = {}
+      flattened.each do |key, value|
+        set_nested_hash_value(structured_hash, key, value, 0, delimiter: delimiter, max_depth: max_depth)
+      end
+
+      deep_freeze_hash(structured_hash)
+      @lock.synchronize do
+        @hashes[cache_key] = structured_hash
+      end
+
+      structured_hash
+    end
+
+    # Check if the cache includes a key. Note that this will return true if you have tried
+    # to fetch a non-existent key since the cache will store that as undefined. This method
+    # is provided for testing purposes.
+    #
+    # @api private
+    # @param key [String, Symbol] setting key
+    # @return [Boolean]
+    def include?(key)
+      @cache.include?(key.to_s)
+    end
+
+    # Get the number of entries in the cache. Note that this will include cache misses as well.
+    #
+    # @api private
+    # @return the number of entries in the cache.
+    def size
+      ensure_cache_up_to_date!
+      @cache.size
+    end
+
+    # Return the cached settings as a key/value hash. Calling this method will load the cache
+    # with the settings if they have not already been loaded.
+    #
+    # @return [Hash]
+    def to_h
+      ensure_cache_up_to_date!
+      hash = {}
+      @cache.each do |key, data|
+        value, _ = data
+        hash[key] = value unless value == NOT_DEFINED
+      end
+      hash
+    end
+
+    # Return true if the cache has already been loaded from the database.
+    #
+    # @return [Boolean]
+    def loaded?
+      !!@last_refreshed
+    end
+
+    # Load all the settings from the database into the cache.
+    def load_settings(asynchronous = false)
+      return if @refreshing
+
+      @lock.synchronize do
+        return if @refreshing
+        @refreshing = true
+        @next_check_at = Time.now + @refresh_interval
+      end
+
+      load_block = lambda do
+        begin
+          values = {}
+          start_time = Time.now
+          Setting.active.each do |setting|
+            values[setting.key] = setting.value.freeze
+          end
+          set_cache_values(start_time) { values }
+        ensure
+          @refreshing = false
+        end
+      end
+
+      if asynchronous
+        Thread.new(&load_block)
+      else
+        load_block.call
+      end
+    end
+
+    # Load only settings that have changed since the last load.
+    def refresh(asynchronous = false)
+      last_refresh_time = @last_refreshed
+      return if last_refresh_time.nil?
+      return if @refreshing
+
+      @lock.synchronize do
+        return if @refreshing
+        @next_check_at = Time.now + @refresh_interval
+        return if @cache.empty?
+        @refreshing = true
+      end
+
+      refresh_block = lambda do
+        begin
+          last_db_update = Setting.last_updated_at
+          if last_db_update.nil? || last_db_update >= last_refresh_time - 1
+            merge_load(last_refresh_time)
+          end
+        ensure
+          @refreshing = false
+        end
+      end
+
+      if asynchronous
+        Thread.new(&refresh_block)
+      else
+        refresh_block.call
+      end
+    end
+
+    # Reset the cache to an unloaded state.
+    def reset
+      @lock.synchronize do
+        @cache = {}.freeze
+        @hashes = {}
+        @last_refreshed = nil
+        @next_check_at = Time.now + @refresh_interval
+        @refreshing = false
+      end
+    end
+
+    # Set the number of seconds to wait between cache refresh checks.
+    #
+    # @param seconds [Numeric]
+    def refresh_interval=(seconds)
+      @lock.synchronize do
+        @refresh_interval = seconds.to_f
+        @next_check_at = Time.now + @refresh_interval if @next_check_at > Time.now + @refresh_interval
+      end
+    end
+
+    # Update a single setting directly into the cache.
+    # @api private
+    def update_setting(setting)
+      return if Coerce.blank?(setting.key)
+      @lock.synchronize do
+        @cache = @cache.merge(setting.key => setting.value)
+        @hashes = {}
+      end
+    end
+
+    # Wait for the settings to be loaded if a new load was triggered. This can happen asynchronously.
+    # @api private
+    def wait_for_load
+      loop do
+        return unless @refreshing
+        sleep(0.001)
+      end
+    end
+
+    private
+
+    # Load just the settings have that changed since the specified timestamp.
+    def merge_load(last_refresh_time)
+      changed_settings = {}
+      start_time = Time.now
+      Setting.updated_since(last_refresh_time - 1).each do |setting|
+        value = (setting.deleted? ? NOT_DEFINED : setting.value)
+        changed_settings[setting.key] = value
+      end
+      set_cache_values(start_time) { @cache.merge(changed_settings) }
+    end
+
+    # Check that cache has update to date data in it. If it doesn't, then sync the
+    # cache with the database.
+    def ensure_cache_up_to_date!
+      if @last_refreshed.nil?
+        # Abort if another thread is already calling load_settings
+        previous_cache_id = @cache.object_id
+        @lock.synchronize do
+          return unless previous_cache_id == @cache.object_id
+        end
+        load_settings(Setting.storage.load_asynchronous?)
+      elsif Time.now >= @next_check_at
+        refresh
+      end
+    end
+
+    # Synchronized method for setting cache and sync meta data.
+    def set_cache_values(refreshed_at_time, &block)
+      @lock.synchronize do
+        @last_refreshed = refreshed_at_time
+        @refreshing = false
+        @cache = block.call.freeze
+        @hashes = {}
+      end
+    end
+
+    # Recusive method for creating a nested hash from delimited keys.
+    def set_nested_hash_value(hash, key, value, current_depth, delimiter:, max_depth:)
+      key, sub_key = (max_depth && current_depth < max_depth ? [key, nil] : key.split(delimiter, 2))
+      if sub_key
+        sub_hash = hash[key]
+        unless sub_hash.is_a?(Hash)
+          sub_hash = {}
+          hash[key] = sub_hash
+        end
+        set_nested_hash_value(sub_hash, sub_key, value, current_depth + 1, delimiter: delimiter, max_depth: max_depth)
+      else
+        hash[key] = value
+      end
+    end
+
+    # Recursively freeze a hash.
+    def deep_freeze_hash(hash)
+      hash.each_value do |value|
+        deep_freeze_hash(value) if value.is_a?(Hash)
+      end
+      hash.freeze
+    end
+  end
+end

data/lib/super_settings/rack_middleware.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "rack"
+
+module SuperSettings
+  # Rack middleware for serving the REST API. See SuperSettings::RestAPI for more details on usage.
+  #
+  # The routes for the API can be mounted under a common path prefix specified in the initializer.
+  #
+  # You must specify some kind of authentication to use this class by at least overriding the
+  # `authenticated?` method in a subclass. How you do this is left up to you since you will most
+  # likely want to integrate in with how the rest of your application authenticates requests.
+  #
+  # You are also responsible for implementing any CSRF protection if your authentication method
+  # uses stateful requests (i.e. cookies or Basic auth where browser automatically include the
+  # credentials on every reqeust). There are other gems available that can be integrated into
+  # your middleware stack to provide this feature. If you need to inject meta elements into
+  # the page, you can do so with the `add_to_head` method.
+  class RackMiddleware
+    RESPONSE_HEADERS = {"Content-Type" => "application/json; charset=utf-8"}.freeze
+
+    # @param app [Object] Rack application or middleware for unhandled requests
+    # @param prefix [String] path prefix for the API routes.
+    def initialize(app, path_prefix = "/")
+      @app = app
+      @path_prefix = path_prefix.to_s.chomp("/")
+    end
+
+    def call(env)
+      if @path_prefix.empty? || "#{env["SCRIPT_NAME"]}#{env["PATH_INFO"]}".start_with?(@path_prefix)
+        handle_request(env)
+      else
+        @app.call(env)
+      end
+    end
+
+    protected
+
+    # Subclasses must implement this method.
+    # @param user [Object] the value returned by the `current_user` method.
+    # @return [Boolean] true if the user is authenticated.
+    def authenticated?(user)
+      raise NotImplementedError
+    end
+
+    # Subclasses can override this method to indicate if the specified user is allowed to view settings.
+    # @param user [Object] the value returned by the `current_user` method.
+    # @return [Boolean] true if the user is can view settings.
+    def allow_read?(user)
+      true
+    end
+
+    # Subclasses can override this method to indicate if the specified user is allowed to change settings.
+    # @param user [Object] the value returned by the `current_user` method.
+    # @return [Boolean] true if the user is can change settings.
+    def allow_write?(user)
+      true
+    end
+
+    # Subclasses can override this method to return the current user object. This object will
+    # be passed to the authenticated?, allow_read?, allow_write?, and changed_by methods.
+    # @param request [Rack::Request] current reqeust object
+    # @return [Object]
+    def current_user(request)
+      nil
+    end
+
+    # Subclasses can override this method to return the information about the current user that will
+    # be stored in the setting history when a setting is changed.
+    # @return [String]
+    def changed_by(user)
+      nil
+    end
+
+    # Subclasses can override this method to return the path to an ERB file to use as the layout
+    # for the HTML application. The layout can use any of the methods defined in SuperSettings::Application::Helper.
+    # @return [String]
+    def layout
+      "layout.html.erb"
+    end
+
+    # Subclasses can override this method to add custom HTML to the <head> element in the HTML application.
+    # This can be used to add additional script or meta tags needed for CSRF protection, etc.
+    # @param request [Rack::Request] current reqeust object
+    # @return [String]
+    def add_to_head(request)
+    end
+
+    # Subclasses can override this method to return the login URL for the application. If this is
+    # provided, then a user will be redirected to that URL if they are not authenticated when loading
+    # the HTML application.
+    # @param request [Rack::Request] current reqeust object
+    # @return [String]
+    def login_url(request)
+    end
+
+    private
+
+    def handle_request(env)
+      request = Rack::Request.new(env)
+      path = request.path[@path_prefix.length, request.path.length]
+      if request.get?
+        if path == "/" || path == ""
+          return handle_root_request(request)
+        elsif path == "/settings"
+          return handle_index_request(request)
+        elsif path == "/setting"
+          return handle_show_request(request)
+        elsif path == "/setting/history"
+          return handle_history_request(request)
+        elsif path == "/last_updated_at"
+          return handle_last_updated_at_request(request)
+        elsif path == "/updated_since"
+          return handle_updated_since_request(request)
+        end
+      elsif request.post?
+        if path == "/settings"
+          return handle_update_request(request)
+        end
+      end
+      @app.call(env)
+    end
+
+    def handle_root_request(request)
+      response = check_authorization(request, write_required: true) do |user|
+        [200, {"Content-Type" => "text/html; charset=utf-8"}, [Application.new(:default, add_to_head(request)).render("index.html.erb")]]
+      end
+
+      if [401, 403].include?(response.first)
+        location = login_url(request)
+        if location
+          response = [302, {"Location" => location}, []]
+        end
+      end
+
+      response
+    end
+
+    def handle_index_request(request)
+      check_authorization(request) do |user|
+        json_response(200, RestAPI.index)
+      end
+    end
+
+    def handle_show_request(request)
+      check_authorization(request) do |user|
+        setting = RestAPI.show(request.params["key"])
+        if setting
+          json_response(200, setting)
+        else
+          json_response(404, nil)
+        end
+      end
+    end
+
+    def handle_update_request(request)
+      check_authorization(request, write_required: true) do |user|
+        result = SuperSettings::RestAPI.update(post_params(request)["settings"], changed_by(user))
+        if result[:success]
+          json_response(200, result)
+        else
+          json_response(422, result)
+        end
+      end
+    end
+
+    def handle_history_request(request)
+      check_authorization(request) do |user|
+        history = RestAPI.history(request.params["key"], limit: request.params["limit"], offset: request.params["offset"])
+        if history
+          json_response(200, history)
+        else
+          json_response(404, nil)
+        end
+      end
+    end
+
+    def handle_last_updated_at_request(request)
+      check_authorization(request) do |user|
+        json_response(200, RestAPI.last_updated_at)
+      end
+    end
+
+    def handle_updated_since_request(request)
+      check_authorization(request) do |user|
+        json_response(200, RestAPI.updated_since(request.params["time"]))
+      end
+    end
+
+    def check_authorization(request, write_required: false)
+      user = current_user(request)
+      return json_response(401, error: "Authentiation required") unless authenticated?(user)
+      allowed = (write_required ? allow_write?(user) : allow_read?(user))
+      return json_response(403, error: "Access denied") unless allowed
+      yield(user)
+    end
+
+    def json_response(status, payload)
+      [status, RESPONSE_HEADERS, [payload.to_json]]
+    end
+
+    def post_params(request)
+      if request.content_type.to_s.match?(/\Aapplication\/json/i) && request.body
+        request.params.merge(JSON.parse(request.body.string))
+      else
+        request.params
+      end
+    end
+  end
+end

data/lib/super_settings/rest_api.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module SuperSettings
+  class RestAPI
+    class << self
+      # Get all settings sorted by key. This endpoint may be called with a REST GET request.
+      #
+      # `GET /`
+      #
+      # The response payload is:
+      # ```
+      # [
+      #   {
+      #     key: string,
+      #     value: object,
+      #     value_type: string,
+      #     description string,
+      #     created_at: iso8601 string,
+      #     updated_at: iso8601 string
+      #   },
+      #   ...
+      # ]
+      # ```
+      def index
+        settings = Setting.active.sort_by(&:key)
+        {settings: settings.collect(&:as_json)}
+      end
+
+      # Get a setting by id.
+      #
+      # `GET /setting`
+      #
+      # Query parameters
+      #
+      # * key - setting key
+      #
+      # The response payload is:
+      # ```
+      # {
+      #   key: string,
+      #   value: object,
+      #   value_type: string,
+      #   description string,
+      #   created_at: iso8601 string,
+      #   updated_at: iso8601 string
+      # }
+      # ```
+      def show(key)
+        Setting.find_by_key(key)&.as_json
+      end
+
+      # The update operation uses a transaction to atomically update all settings.
+      #
+      # `POST /settings`
+      #
+      # The format of the parameters is an array of hashes with each setting identified by the key.
+      # The settings should include either `value` and `value_type` (and optionally `description`) to
+      # insert or update a setting, or `deleted` to delete the setting.
+      #
+      # ```
+      # { settings: [
+      #     {
+      #       key: string,
+      #       value: object,
+      #       value_type: string,
+      #       description: string,
+      #     },
+      #     {
+      #       key: string,
+      #       deleted: boolean,
+      #     },
+      #     ...
+      #   ]
+      # }
+      # ```
+      #
+      # The response will be either `{success: true}` or `{success: false, errors: {key => [string], ...}}`
+      def update(settings_params, changed_by = nil)
+        all_valid, settings = Setting.bulk_update(Array(settings_params), changed_by)
+        if all_valid
+          {success: true}
+        else
+          errors = {}
+          settings.each do |setting|
+            if setting.errors.any?
+              errors[setting.key] = setting.errors.values.flatten
+            end
+          end
+          {success: false, errors: errors}
+        end
+      end
+
+      # Return the history of the setting.
+      #
+      # `GET /setting/history`
+      #
+      # Query parameters
+      #
+      # * key - setting key
+      # * limit - number of history items to return
+      # * offset - index to start fetching items from (most recent items are first)
+      #
+      # The response format is:
+      # ```
+      # {
+      #   key: string,
+      #   encrypted: boolean,
+      #   histories: [
+      #     {
+      #       value: object,
+      #       changed_by: string,
+      #       created_at: iso8601 string
+      #     },
+      #     ...
+      #   ],
+      #   previous_page_params: hash,
+      #   next_page_params: hash
+      # }
+      # ```
+      def history(key, limit: nil, offset: 0)
+        setting = Setting.find_by_key(key)
+        return nil unless setting
+
+        offset = [offset.to_i, 0].max
+        limit = limit.to_i
+        fetch_limit = (limit > 0 ? limit + 1 : nil)
+        histories = setting.history(limit: fetch_limit, offset: offset)
+
+        payload = {key: setting.key, encrypted: setting.encrypted?}
+
+        if limit > 0 && !histories.empty?
+          if offset > 0
+            previous_page_params = {key: setting.key, offset: [offset - limit, 0].max, limit: limit}
+          end
+          if histories.size > limit
+            histories = histories.take(limit)
+            next_page_params = {key: setting.key, offset: offset + limit, limit: limit}
+          end
+          payload[:previous_page_params] = previous_page_params if previous_page_params
+          payload[:next_page_params] = next_page_params if next_page_params
+        end
+
+        payload[:histories] = histories.collect do |history|
+          history_values = {value: history.value, changed_by: history.changed_by_display, created_at: history.created_at}
+          history_values[:deleted] = true if history.deleted?
+          history_values
+        end
+
+        payload
+      end
+
+      # Return the timestamp of the most recently updated setting.
+      #
+      # `GET /last_updated_at`
+      #    #
+      # The response payload is:
+      # {
+      #   last_updated_at: iso8601 string
+      # }
+      def last_updated_at
+        {last_updated_at: Setting.last_updated_at.utc.iso8601}
+      end
+
+      # Return settings that have been updated since a specified timestamp.
+      #
+      # `GET /updated_since`
+      #
+      # Query parameters
+      #
+      # * time - iso8601 string
+      #
+      # The response payload is:
+      # ```
+      # [
+      #   {
+      #     key: string,
+      #     value: object,
+      #     value_type: string,
+      #     description string,
+      #     created_at: iso8601 string,
+      #     updated_at: iso8601 string
+      #   },
+      #   ...
+      # ]
+      # ```
+      def updated_since(time)
+        time = Coerce.time(time)
+        settings = Setting.updated_since(time)
+        {settings: settings.collect(&:as_json)}
+      end
+    end
+  end
+end