super_settings 0.0.0.rc1 → 0.0.1.rc1

data/lib/super_settings/engine.rb

@@ -46,11 +46,6 @@ module SuperSettings
         Setting.cache = (configuration.model.cache || Rails.cache)
         Setting.storage = configuration.model.storage_class
 
-        if configuration.secret.present?
-          SuperSettings.secret = configuration.secret
-          configuration.secret = nil
-        end
-
         if !SuperSettings.loaded?
           begin
             SuperSettings.load_settings

data/lib/super_settings/history_item.rb

@@ -16,8 +16,16 @@ module SuperSettings
 
     # The method could be overriden to change how the changed_by attribute is displayed.
     # For instance, you could store a user id in the changed_by column and add an association
-    # on this model `belongs_to :user, class_name: "User", foreign_key: :changed_by` and then
-    # define this method as `user.name`.
+    # on this model.
+    #
+    # @example
+    #   class SuperSettings::HistoryItem
+    #     def changed_by_display
+    #       user = User.find_by(id: changed_by) if changed_by
+    #       user ? user.name : changed_by
+    #     end
+    #   end
+    #
     # @return [String]
     def changed_by_display
       changed_by

data/lib/super_settings/local_cache.rb

@@ -20,7 +20,7 @@ module SuperSettings
     # 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
+    # @param refresh_interval [Numeric] number of seconds to wait between checking for setting updates
     def initialize(refresh_interval:)
       @refresh_interval = refresh_interval
       @lock = Mutex.new
@@ -65,7 +65,18 @@ module SuperSettings
     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}}}`).
+    # to create a nested hash.
+    #
+    # @example
+    #   Setting with key "a.b.c" and value 1 becomes
+    #
+    #   {
+    #     "a" => {
+    #       "b" => {
+    #         "c" => 1
+    #       }
+    #     }
+    #   }
     #
     # See SuperSettings.structured for more details.
     def structured(key = nil, delimiter: ".", max_depth: nil)
@@ -282,7 +293,7 @@ module SuperSettings
 
     # 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))
+      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)

data/lib/super_settings/{rack_middleware.rb → rack_application.rb}

@@ -8,22 +8,40 @@ module SuperSettings
   # 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
+  # +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
+  # the page, you can do so with the +add_to_head+ method.
+  class RackApplication
+    RESPONSE_HEADERS = {"content-type" => "application/json; charset=utf-8", "cache-control" => "no-cache"}.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 = "/")
+    # @param path_prefix [String] path prefix for the API routes.
+    # @yield Block to be evaluated on the instance to extend it's behavior. You can use
+    #   this to define the access control methods rather than having to extend the class.
+    #
+    # @example
+    #
+    #   app = SuperSettings::RackApplication.new do
+    #     def current_user(request)
+    #       auth = request["HTTP_AUTHORIZATION"]
+    #       token_match = auth&.match(/\ABearer:\s*(.*)/)
+    #       token = token_match[1] if token_match
+    #       User.identified_by(token)
+    #     end
+    #
+    #     def allow_write?(user)
+    #       user.admin?
+    #     end
+    #   end
+    def initialize(app = nil, path_prefix = "/", &block)
       @app = app
       @path_prefix = path_prefix.to_s.chomp("/")
+      instance_eval(&block) if block
     end
 
     def call(env)
@@ -34,39 +52,45 @@ module SuperSettings
       end
     end
 
-    protected
+    # Subclasses must 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 request object
+    # @return [Object]
+    def current_user(request)
+      raise NotImplementedError
+    end
 
-    # Subclasses must implement this method.
-    # @param user [Object] the value returned by the `current_user` method.
+    # Subclasses can override this method to indicate if a user is authenticated. By default
+    # a request will be considered authenticated if the +current_user+ method returns a value.
+    #
+    # @param user [Object] the value returned by the +current_user+ method.
     # @return [Boolean] true if the user is authenticated.
     def authenticated?(user)
-      raise NotImplementedError
+      !!user
     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.
+    # By default if a user is authenticated they will be able to read 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.
+    # By default if a user can read settings, then they will be able to write them as well.
+    #
+    # @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
+      allow_read?(user)
     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.
+    # Subclasses can override this method to return the information to record about the current user
+    # that will be stored in the setting history when a setting is changed.
+    #
     # @return [String]
     def changed_by(user)
       nil
@@ -74,6 +98,7 @@ module SuperSettings
 
     # 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"
@@ -81,17 +106,18 @@ module SuperSettings
 
     # 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)
+    # Subclasses can override this method to disable the web UI component of the application on only
+    # expose the REST API.
+    #
+    # @return [Boolean]
+    def web_ui_enabled?
+      true
     end
 
     private
@@ -100,7 +126,7 @@ module SuperSettings
       request = Rack::Request.new(env)
       path = request.path[@path_prefix.length, request.path.length]
       if request.get?
-        if path == "/" || path == ""
+        if (path == "/" || path == "") && web_ui_enabled?
           return handle_root_request(request)
         elsif path == "/settings"
           return handle_index_request(request)
@@ -118,18 +144,22 @@ module SuperSettings
           return handle_update_request(request)
         end
       end
-      @app.call(env)
+
+      if @app
+        @app.call(env)
+      else
+        [404, {"content-type" => "text/plain"}, ["Not found"]]
+      end
     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")]]
+        [200, {"content-type" => "text/html; charset=utf-8", "cache-control" => "no-cache"}, [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}, []]
+        if SuperSettings.authentication_url
+          response = [302, {"location" => SuperSettings.authentication_url}, []]
         end
       end
 
@@ -196,7 +226,7 @@ module SuperSettings
     end
 
     def json_response(status, payload)
-      [status, RESPONSE_HEADERS, [payload.to_json]]
+      [status, RESPONSE_HEADERS.dup, [payload.to_json]]
     end
 
     def post_params(request)

data/lib/super_settings/rest_api.rb

@@ -7,22 +7,21 @@ module SuperSettings
     class << self
       # Get all settings sorted by key. This endpoint may be called with a REST GET request.
       #
-      # `GET /`
+      # @example
+      #   GET /
       #
-      # The response payload is:
-      # ```
-      # [
-      #   {
-      #     key: string,
-      #     value: object,
-      #     value_type: string,
-      #     description string,
-      #     created_at: iso8601 string,
-      #     updated_at: iso8601 string
-      #   },
-      #   ...
-      # ]
-      # ```
+      #   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)}
@@ -30,53 +29,57 @@ module SuperSettings
 
       # Get a setting by id.
       #
-      # `GET /setting`
+      # @example
+      #   GET /setting
       #
-      # Query parameters
+      #   Query parameters
       #
-      # * key - setting key
+      #   * key - setting key
       #
-      # The response payload is:
-      # ```
-      # {
-      #   key: string,
-      #   value: object,
-      #   value_type: string,
-      #   description string,
-      #   created_at: iso8601 string,
-      #   updated_at: iso8601 string
-      # }
-      # ```
+      #   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`
+      # @example
+      #   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.
+      #   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,
-      #     },
-      #     ...
-      #   ]
-      # }
-      # ```
+      #   { settings: [
+      #       {
+      #         key: string,
+      #         value: object,
+      #         value_type: string,
+      #         description: string,
+      #       },
+      #       {
+      #         key: string,
+      #         deleted: boolean,
+      #       },
+      #       ...
+      #     ]
+      #   }
+      #
+      #   The response will be either
       #
-      # The response will be either `{success: true}` or `{success: false, errors: {key => [string], ...}}`
+      #   {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
@@ -94,41 +97,39 @@ module SuperSettings
 
       # Return the history of the setting.
       #
-      # `GET /setting/history`
+      # @example
+      #   GET /setting/history
       #
-      # Query parameters
+      #   Query parameters
       #
-      # * key - setting key
-      # * limit - number of history items to return
-      # * offset - index to start fetching items from (most recent items are first)
+      #   * 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
-      # }
-      # ```
+      #   The response format is:
+      #   {
+      #     key: string,
+      #     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)
+        fetch_limit = ((limit > 0) ? limit + 1 : nil)
         histories = setting.history(limit: fetch_limit, offset: offset)
 
-        payload = {key: setting.key, encrypted: setting.encrypted?}
+        payload = {key: setting.key}
 
         if limit > 0 && !histories.empty?
           if offset > 0
@@ -153,38 +154,38 @@ module SuperSettings
 
       # Return the timestamp of the most recently updated setting.
       #
-      # `GET /last_updated_at`
-      #    #
-      # The response payload is:
-      # {
-      #   last_updated_at: iso8601 string
-      # }
+      # @example
+      #   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`
+      # @example
+      #   GET /updated_since
       #
-      # Query parameters
+      #   Query parameters
       #
-      # * time - iso8601 string
+      #   * time - iso8601 string
       #
-      # The response payload is:
-      # ```
-      # [
-      #   {
-      #     key: string,
-      #     value: object,
-      #     value_type: string,
-      #     description string,
-      #     created_at: iso8601 string,
-      #     updated_at: 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)