skinny_controllers 0.1 → 0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 22e75d7a70d070311ace3af0a33cfa1df96dce4d
-  data.tar.gz: cee31b4824b93e8d425746a443212c1f36ca7f31
+  metadata.gz: ad259a752520b2a0fbfd467b7f4dd50ee97ba1a2
+  data.tar.gz: b2a7c7b3d82895b1e66b1677f0137c6d91947503
 SHA512:
-  metadata.gz: 0e1c99dd3bfd118eac0cb5081327328bf0dfbee23a5f93cee0a2d9fdf9f30d22eebab32aa0e7b6329a903ba88788a3e488893f12a6c0311f6153bc3a837adb61
-  data.tar.gz: e8ad57f6833d21b4148f8f5307e262d072698f83d114a027813297e7ad831df38afcce29436964077814935c5c3fc590855c4b2ca8335da1643cdd15800873e7
+  metadata.gz: 5d276829328864ccc91cda85e6b7c866a7e22b397fe598645eb0b5b2e0414c9bf23b54b13233951f56e156221a351d1ecd753be7339cd28ba1e016f6d8696fee
+  data.tar.gz: cc2d9d76498663038ea08a401cff03672da41115cfa1aa35b9f4ac4530129387225d699351e91f46d5b686c3411e321653f7c2b1e755fa79ffc5fdf717f59e9a

data/README.md

@@ -9,6 +9,8 @@ An implementation of role-based policies and operations to help controllers lose
 
 The goal of this project is to help API apps be more slim, and separate logic as much as possible.
 
+This gem is inspired by [trailblazer](https://github.com/apotonick/trailblazer), following similar patterns, yet allowing the structure of the rails app to not be entirely overhauled.
+
 # Installation
 
 ```ruby
@@ -20,4 +22,117 @@ or
 
 # Usage
 
-TODO: this section
+## In a controller:
+
+```ruby
+include SkinnyControllers::Diet
+# ...
+# in your action
+render json: model
+```
+
+and that's it!
+
+The above does a multitude of assumptions to make sure that you can type the least amount code possible.
+
+1. Your controller name is based off your model name (configurable per controller)
+2. Any defined policies or operations follow the formats (though they don't have to exist):
+  - `#{Model.name}Policy`
+  - `#{Model.name}Operations`
+3. Your model responds to `find`, and `where`
+4. Your model responds to `is_accessible_to?`. This can be changed at `SkinnyControllers.accessible_to_method`
+
+### Your model name is different from your resource name
+Lets say you have a JSON API resource that you'd like to render that has some additional/subset of data.
+Maybe the model is an `Event`, and the resource an `EventSummary` (which could do some aggregation of `Event` data).
+
+The naming of all the objects should be as follows:
+ - `EventSummariesController`
+ - `EventSummaryOperations::*`
+ - `EventSummaryPolicy`
+ - and the model is still `Event`
+
+In `EventSummariesController`, you would make the following additions:
+```ruby
+class EventSummariesController < ApiController # or whatever your superclass is
+  include SkinnyControllers::Diet
+  model_class = Event
+
+  def index
+    render json: model, each_serializer: EventSummariesSerializer
+  end
+
+  def show
+    render json: model, serializer: EventSummariesSerializer
+  end
+end
+```
+Note that `each_serializer` and `serializer` is not part of `SkinnyControllers`, and is part of [ActiveModel::Serializers](https://github.com/rails-api/active_model_serializers).
+
+## Defining Operations
+
+Operations should be placed in `app/operations` of your rails app.
+
+For operations concerning an `Event`, they should be under `app/operations/event_operations/`.
+
+Using the example from the specs:
+```ruby
+module EventOperations
+  class Read < SkinnyControllers::Operation::Base
+    def run
+      model if allowed?
+    end
+  end
+end
+```
+
+alternatively, all operation verbs can be stored in the same file under (for example) `app/operations/user_operations.rb`
+
+```ruby
+module UserOperations
+  class Read < SkinnyControllers::Operation::Base
+    def run
+      model if allowed?
+    end
+  end
+
+  class ReadAll < SkinnyControllers::Operation::Base
+    def run
+      model if allowed?
+    end
+  end
+end
+```
+
+
+## Defining Policies
+
+Policies should be placed in `app/policies` of your rails app.
+These are where you define your access logic, and how to decide if a user has access to the `object`
+
+```ruby
+class EventPolicy < SkinnyControllers::Policy::Base
+  def read?(o = object)
+    o.is_accessible_to?(user)
+  end
+end
+```
+
+
+## Globally Configurable Options
+
+All of these can be set on `SkinnyControllers`,
+e.g.:
+```ruby
+SkinnyControllers.controller_namespace = 'API'
+```
+
+The following options are available:
+ - `operations_namespace`
+ - `operations_suffix`
+ - `policy_suffix`
+ - `controller_namespace` defaults to `''`
+ - `allow_by_default` defaults to `true`
+ - `accessible_to_method` defaults to `is_accessible_to?`
+ - `accessible_to_scope` defaults to `accessible_to`
+ - `action_map` see [skinny_controllers.rb](./lib/skinny_controllers.rb#L61)

data/lib/skinny_controllers/diet.rb

@@ -31,9 +31,11 @@ module SkinnyControllers
     end
 
     def default_operation_namespace_for(model_name)
-      parent_namespace = Operation::Default.name.deconstantize
-      namespace = "#{parent_namespace}::#{model_name}".safe_constantize
-      namespace || Operation.const_set(model_name, Module.new)
+      desired_namespace = operation_namespace_from_model(model_name)
+
+      parent_namespace = SkinnyControllers.operations_namespace
+      namespace = "#{parent_namespace}::#{desired_namespace}".safe_constantize
+      namespace || Object.const_set(desired_namespace, Module.new)
     end
 
     # abstraction for `operation.run`
@@ -46,6 +48,10 @@ module SkinnyControllers
 
     private
 
+    def operation_namespace_from_model(model_name)
+      "#{model_name}#{SkinnyControllers::operations_suffix}"
+    end
+
     # action name is inherited from ActionController::Base
     # http://www.rubydoc.info/docs/rails/2.3.8/ActionController%2FBase%3Aaction_name
     def verb_for_action
@@ -65,8 +71,9 @@ module SkinnyControllers
     end
 
     def operation_class_from_model(model_name)
-      prefix = SkinnyControllers.operation_namespace
-      "#{prefix}::#{model_name}::#{verb_for_action}"
+      prefix = SkinnyControllers.operations_namespace
+      namespace = operation_namespace_from_model(model_name)
+      "#{prefix}::#{namespace}::#{verb_for_action}"
     end
 
     def controller_name_prefix

data/lib/skinny_controllers/operation/base.rb

@@ -18,10 +18,9 @@ module SkinnyControllers
 
       attr_accessor :params, :current_user, :authorized_via_parent
 
-      class << self
-        def run(current_user, params)
-          new(current_user, params).run
-        end
+      def self.run(current_user, params)
+        object = self.new(current_user, params)
+        object.run
       end
 
       def initialize(current_user, params)
@@ -42,11 +41,29 @@ module SkinnyControllers
       end
 
       def object_class
-        @object_class ||= object_type_of_interest.demodulize.constantize
+        unless @object_class
+          # "Namespace::Model" => "Model"
+          model_name = object_type_of_interest.demodulize
+          # "Model" => Model
+          @object_class = model_name.constantize
+        end
+
+        @object_class
       end
 
       def object_type_of_interest
-        @object_type_name ||= self.class.name.deconstantize.demodulize
+        unless @object_type_name
+          # Namespace::ModelOperations::Verb
+          klass_name = self.class.name
+          # Namespace::ModelOperations::Verb => Namespace::ModelOperations
+          namespace = klass_name.deconstantize
+          # Namespace::ModelOperations => ModelOperations
+          nested_namespace = namespace.demodulize
+          # ModelOperations => Model
+          @object_type_name = nested_namespace.gsub(SkinnyControllers.operations_suffix, '')
+        end
+
+        @object_type_name
       end
 
       def association_name_from_object

data/lib/skinny_controllers/operation/model_helpers.rb

@@ -4,12 +4,14 @@ module SkinnyControllers
       def model
         # TODO: not sure if multiple ids is a good idea here
         # if we don't have a(ny) id(s), get all of them
+
+
         @model ||=
           if id_from_params
             model_from_id
           elsif params[:scope]
             model_from_scope
-          elsif key = params.keys.grep(/_id$/)
+          elsif (key = params.keys.grep(/\_id$/)).present?
             # hopefully there is only ever one of these passed
             model_from_named_id(key.first)
           else
@@ -17,10 +19,15 @@ module SkinnyControllers
           end
       end
 
+      def sanitized_params
+        keys = (object_class.column_names & params.keys)
+        params.slice(*keys).symbolize_keys
+      end
+
       def scoped_model(scoped_params)
         unless @scoped_model
           klass_name = scoped_params[:type]
-          operation_name = "Operations::#{klass_name}::Read"
+          operation_name = operation_for(klass_name, 'Read'.freeze)
           operation = operation_name.constantize.new(current_user, id: scoped_params[:id])
           @scoped_model = operation.run
           self.authorized_via_parent = !!@scoped_model
@@ -29,8 +36,26 @@ module SkinnyControllers
         @scoped_model
       end
 
+      def operation_for(klass_name, verb)
+        operations_class_namespace +
+        klass_name +
+        SkinnyControllers.operations_suffix +
+        "::#{verb}"
+      end
+
+      def operations_class_namespace
+        namespace = SkinnyControllers.policies_namespace
+        "#{namespace}::" if namespace
+      end
+
       def model_from_params
-        object_class.where(params).accessible_to(current_user)
+        ar_proxy = object_class.where(sanitized_params)
+
+        if ar_proxy.respond_to? SkinnyControllers.accessible_to_scope
+          return ar_proxy.accessible_to(current_user)
+        end
+
+        ar_proxy
       end
 
       def model_from_named_id(key)

data/lib/skinny_controllers/operation/policy_helpers.rb

@@ -1,22 +1,27 @@
 module SkinnyControllers
   module Operation
     module PolicyHelpers
-      POLICY_CLASS_PREFIX = 'Policy::'.freeze
-      POLICY_CLASS_SUFFIX = 'Policy'.freeze
-      POLICY_SUFFIX = '?'.freeze
+      POLICY_METHOD_SUFFIX = '?'.freeze
 
+      # Takes the class name of self and converts it to a Policy class name
+      #
+      # @example In Operation::Event::Read, Policy::EventPolicy is returned
       def policy_class
         @policy_class ||= (
-          POLICY_CLASS_PREFIX +
+          policy_class_namespace +
           object_type_of_interest +
-          POLICY_CLASS_SUFFIX
+          SkinnyControllers.policy_suffix
         ).constantize
       end
 
-      def policy_name
-        @policy_name ||= self.class.name.demodulize.downcase + POLICY_SUFFIX
+      # Converts the class name to the method name to call on the policy
+      #
+      # @example Operation::Event::Read would become read?
+      def policy_method_name
+        @policy_method_name ||= self.class.name.demodulize.downcase + POLICY_METHOD_SUFFIX
       end
 
+      # @return a new policy object and caches it
       def policy_for(object)
         @policy ||= policy_class.new(
           current_user,
@@ -25,12 +30,19 @@ module SkinnyControllers
       end
 
       def allowed?
-        policy_for(model)
+        allowed_for?(model)
       end
 
       # checks the policy
       def allowed_for?(object)
-        policy_for(object).send(policy_name)
+        policy_for(object).send(policy_method_name)
+      end
+
+      private
+
+      def policy_class_namespace
+        namespace = SkinnyControllers.policies_namespace
+        "#{namespace}::" if namespace
       end
     end
   end

data/lib/skinny_controllers/policy/base.rb

@@ -3,21 +3,40 @@ module SkinnyControllers
     class Base
       attr_accessor :user, :object, :authorized_via_parent
 
+      # @param [User] user the being to check if they have access to `object`
+      # @param [ActiveRecord::Base] object the object that we are wanting to check
+      #    the authorization of `user` for
+      # @param [Boolean] authorized_via_parent if this object is authorized via
+      #    a prior authorization from a parent class / association
       def initialize(user, object, authorized_via_parent: false)
         self.user = user
         self.object = object
         self.authorized_via_parent = authorized_via_parent
       end
 
+      # if a method is not defined for a particular verb or action,
+      # this will be used.
+      #
+      # @example Operation::Object::SendReceipt.run is called, since
+      #    `send_receipt` doesn't exist in this class, this `default?`
+      #    method will be used.
       def default?
         SkinnyControllers.allow_by_default
       end
 
-      # defaults
+      # this should be used when checking access to a single object
       def read?(o = object)
-        o.is_accessible_to? user
+        o.send(accessible_method, user)
       end
 
+      # this should be used when checking access to multilpe objects
+      # it will call `read?` on each object of the array
+      #
+      # if the operation used a scope to find records from
+      # an association, then `authorized_via_parent` could be true,
+      # in which case, the loop would be skipped.
+      #
+      # TODO: think of a way to override the authorized_via_parent functionality
       def read_all?
         return true if authorized_via_parent
         # This is expensive, so try to avoid it
@@ -27,6 +46,12 @@ module SkinnyControllers
         accessible = object.map { |ea| read?(ea) }
         accessible.all?
       end
+
+      private
+
+      def accessible_method
+        SkinnyControllers.accessible_to_method
+      end
     end
   end
 end

data/lib/skinny_controllers/version.rb

@@ -1,3 +1,3 @@
 module SkinnyControllers
-  VERSION = 0.1
+  VERSION = 0.2
 end

data/lib/skinny_controllers.rb

@@ -15,6 +15,12 @@ require 'skinny_controllers/operation/default'
 require 'skinny_controllers/diet'
 require 'skinny_controllers/version'
 
+# load the policies and operations to the top level name space.
+if defined? Rails
+  $LOAD_PATH.unshift Rails.root + '/app/operations'
+  $LOAD_PATH.unshift Rails.root + '/app/policies'
+end
+
 module SkinnyControllers
   # Tells the Diet what namespace of the controller
   # isn't going to be part of the model name
@@ -25,15 +31,34 @@ module SkinnyControllers
   #  # 'API::' would be removed from 'API::Namespace::ObjectNamesController'
   cattr_accessor :controller_namespace
 
-  #
-  cattr_accessor :operation_namespace do
-    'Operation'.freeze
+  cattr_accessor :operations_suffix do
+    'Operations'
+  end
+
+  cattr_accessor :policy_suffix do
+    'Policy'
+  end
+
+  cattr_accessor :operations_namespace do
+    ''.freeze
+  end
+
+  cattr_accessor :policies_namespace do
+    ''.freeze
   end
 
   cattr_accessor :allow_by_default do
     true
   end
 
+  cattr_accessor :accessible_to_method do
+    :is_accessible_to?
+  end
+
+  cattr_accessor :accessible_to_scope do
+    :accessible_to
+  end
+
   # the diet uses ActionController::Base's
   # `action_name` method to get the current action.
   # From that action, we map what verb we want to use for our operation
@@ -45,9 +70,11 @@ module SkinnyControllers
   cattr_accessor :action_map do
     {
       'default'.freeze => DefaultVerbs::Read,
-      'create'.freeze => DefaultVerbs::Create,
       'index'.freeze => DefaultVerbs::ReadAll,
       'destroy'.freeze => DefaultVerbs::Delete,
+      # these two are redundant, as the action will be
+      # converted to a verb via inflection
+      'create'.freeze => DefaultVerbs::Create,
       'update'.freeze => DefaultVerbs::Update
     }
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: skinny_controllers
 version: !ruby/object:Gem::Version
-  version: '0.1'
+  version: '0.2'
 platform: ruby
 authors:
 - L. Preston Sego III
@@ -25,7 +25,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -39,7 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: awesome_print
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -53,7 +53,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: codeclimate-test-reporter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: awesome_print
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -81,7 +95,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: codeclimate-test-reporter
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -95,7 +109,63 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rubocop
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: factory_girl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: factory_girl_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -148,5 +218,5 @@ rubyforge_project:
 rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
-summary: SkinnyControllers-0.1
+summary: SkinnyControllers-0.2
 test_files: []