wallaby-core 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b808379fa5d1d1105d40bd2c9f6f960c0c2ebbfab0fffead3c483b1cd07fab4d
-  data.tar.gz: 1cdfde9da6cf530b366fb31a5ed659d9d4175181cb8ec28b6588f686a50a7ece
+  metadata.gz: e734b411c2c25a8eb828f0a3610a868aea0da1ec3292ead6422494a7e69fe4f3
+  data.tar.gz: 37c0db19ed98a67512706633ca4c99120de9bdd0e246ee66d91cf19c536bfa5a
 SHA512:
-  metadata.gz: 81f0c8d139ec9975ce47ffb157fb12c273f44c7496c8b071d40e0fed1498226e19ca7ab3254fe2d825b0ed8936a74db1341f2c40d0e3dfa46091880603dbeba2
-  data.tar.gz: fb8f6be411fb84876a7ed7a1f9aa0f5f51341e97a3bdd6d2803c6357c1e8f32bed20d9b11e14bad886f926123d33a65bd49879a572f318b56ddc3a8bb4c897c4
+  metadata.gz: 80179286ff0d8c67f99d3881fec98791d436047de690a79de6b3a0df204ba8d132265111e78a00997e6d0188e1c04e36e5811aa9a9b2bcaacbb7e76492a833b5
+  data.tar.gz: 431ca7009491c389d0b0f34862077daa4214b5f6a8c75c44b5c5291fdeec09f607452bec1700dde50bd9c8449cd3d9c7f15b47821269f2fa57d921e0a3f20f6c

data/README.md

@@ -7,7 +7,7 @@
 [![Test Coverage](https://api.codeclimate.com/v1/badges/f16f8d87553424c1aacc/test_coverage)](https://codeclimate.com/github/wallaby-rails/wallaby-core/test_coverage)
 [![Inch CI](https://inch-ci.org/github/wallaby-rails/wallaby-core.svg?branch=master)](https://inch-ci.org/github/wallaby-rails/wallaby-core)
 
-Wallaby::Core contains all the core interfaces that [Wallaby](https://github.com/wallaby-rails/wallaby) gem is built upon.
+Wallaby::Core holds all the core interfaces that [Wallaby](https://github.com/wallaby-rails/wallaby) gem is built upon.
 
 ## Install
 

data/app/controllers/wallaby/resources_controller.rb

@@ -5,8 +5,17 @@ module Wallaby
 
   # Resources controller, superclass for all customization controllers.
   # It contains CRUD template action methods
-  # (`index`/`new`/`create`/`edit`/`update`/`destroy`)
+  # ({Wallaby::ResourcesConcern#index #index} / {Wallaby::ResourcesConcern#new #new}
+  # / {Wallaby::ResourcesConcern#create #create} / {Wallaby::ResourcesConcern#edit #edit}
+  # / {Wallaby::ResourcesConcern#update #update} / {Wallaby::ResourcesConcern#destroy #destroy})
   # that allow subclasses to override.
+  #
+  # For better practice, please create an application controller class (see example)
+  # to better control the functions shared between different resource controllers.
+  # @example Create an application class for Admin Interface usage
+  #   class Admin::ApplicationController < Wallaby::ResourcesController
+  #     base_class!
+  #   end
   class ResourcesController
     include ResourcesConcern
   end

data/config/locales/wallaby_class.en.yml

@@ -1,9 +1,9 @@
 en:
   wallaby:
     map:
-      missing_mode_for_model_class: "[WALLABY] Don't know how to handle this model %{model}."
+      missing_mode_for_model_class: "Don't know how to handle this model %{model}."
       model_class_mapper:
-        missing_model_class: "[WALLABY] Please define self.model_class for %{model} or set it as global.\n          @see Wallaby.configuration.mapping"
+        missing_model_class: "Please define self.model_class for %{model} or set it as global.\n          @see Wallaby.configuration.mapping"
 
     mode:
       inherit_required: '%{klass} must inherit from %{parent}.'

data/lib/adaptors/wallaby/custom/default_provider.rb

@@ -2,7 +2,7 @@
 
 module Wallaby
   class Custom
-    # Default provider for custom mode
+    # Default authorization provider for {Wallaby::Custom} mode that whitelists everything.
     class DefaultProvider < DefaultAuthorizationProvider
     end
   end

data/lib/adaptors/wallaby/custom/model_decorator.rb

@@ -2,7 +2,7 @@
 
 module Wallaby
   class Custom
-    # Custom modal decorator
+    # {Wallaby::Custom} mode decorator that only pulls out all the attributes from setter/getter methods.
     class ModelDecorator < ::Wallaby::ModelDecorator
       # Assume that attributes come from the setter/getter, e.g. `name=`/`name`
       # @return [ActiveSupport::HashWithIndifferentAccess] metadata
@@ -11,8 +11,7 @@ module Wallaby
           ::ActiveSupport::HashWithIndifferentAccess.new.tap do |hash|
             methods = model_class.public_instance_methods(false).map(&:to_s)
             methods
-              .grep(/[^=]$/)
-              .select { |method_id| methods.include? "#{method_id}=" }
+              .grep(/[^=]$/).select { |method_id| methods.include? "#{method_id}=" }
               .each { |attribute| hash[attribute] = { label: attribute.humanize, type: 'string' } }
           end.freeze
       end
@@ -50,21 +49,23 @@ module Wallaby
         @form_field_names ||= form_fields.keys - [primary_key.to_s]
       end
 
+      # @param resource [Object]
       # @return [ActiveModel::Errors]
       def form_active_errors(resource)
         @form_active_errors ||= ActiveModel::Errors.new resource
       end
 
-      # @return [String, Symbole] primary key name
+      # @return [String, Symbole] default to `:id`
       def primary_key
         @primary_key ||= :id
       end
 
       # @param resource [Object]
-      # @return [String]
+      # @return [String, nil]
       def guess_title(resource)
-        field_name = FieldUtils.first_field_by({ name: /name|title|subject/ }, fields)
-        ModuleUtils.try_to resource, field_name
+        FieldUtils
+          .first_field_by({ name: /name|title|subject/ }, fields)
+          .try { |field_name| resource.try field_name }
       end
     end
   end

data/lib/adaptors/wallaby/custom/model_finder.rb

@@ -2,9 +2,10 @@
 
 module Wallaby
   class Custom
-    # Model finder
+    # Model finder for {Wallaby::Custom} mode that returns the list of model set by
+    # {Wallaby::Configuration#custom_models}
     class ModelFinder < ::Wallaby::ModelFinder
-      # @return [Array<Class>] a list of classes
+      # @return [Wallaby::ClashArray] a list of classes
       def all
         Wallaby.configuration.custom_models.presence
       end

data/lib/adaptors/wallaby/custom/model_pagination_provider.rb

@@ -2,7 +2,7 @@
 
 module Wallaby
   class Custom
-    # Model pagination provider
+    # Model pagination provider for {Wallaby::Custom} mode
     class ModelPaginationProvider < ::Wallaby::ModelPaginationProvider
       # By default, it doesn't support pagination
       # @return [false]

data/lib/adaptors/wallaby/custom/model_service_provider.rb

@@ -2,47 +2,8 @@
 
 module Wallaby
   class Custom
-    # Model service provider
+    # Model service provider for {Wallaby::Custom} mode
     class ModelServiceProvider < ::Wallaby::ModelServiceProvider
-      # @raise [Wallaby::NotImplemented]
-      def permit(*)
-        raise Wallaby::NotImplemented, Locale.t('errors.not_implemented.model_servicer', method_name: __callee__)
-      end
-
-      # @raise [Wallaby::NotImplemented]
-      def collection(*)
-        raise Wallaby::NotImplemented, Locale.t('errors.not_implemented.model_servicer', method_name: __callee__)
-      end
-
-      # @raise [Wallaby::NotImplemented]
-      def paginate(*)
-        raise Wallaby::NotImplemented, Locale.t('errors.not_implemented.model_servicer', method_name: __callee__)
-      end
-
-      # @raise [Wallaby::NotImplemented]
-      def new(*)
-        raise Wallaby::NotImplemented, Locale.t('errors.not_implemented.model_servicer', method_name: __callee__)
-      end
-
-      # @raise [Wallaby::NotImplemented]
-      def find(*)
-        raise Wallaby::NotImplemented, Locale.t('errors.not_implemented.model_servicer', method_name: __callee__)
-      end
-
-      # @raise [Wallaby::NotImplemented]
-      def create(*)
-        raise Wallaby::NotImplemented, Locale.t('errors.not_implemented.model_servicer', method_name: __callee__)
-      end
-
-      # @raise [Wallaby::NotImplemented]
-      def update(*)
-        raise Wallaby::NotImplemented, Locale.t('errors.not_implemented.model_servicer', method_name: __callee__)
-      end
-
-      # @raise [Wallaby::NotImplemented]
-      def destroy(*)
-        raise Wallaby::NotImplemented, Locale.t('errors.not_implemented.model_servicer', method_name: __callee__)
-      end
     end
   end
 end

data/lib/authorizers/wallaby/cancancan_authorization_provider.rb

@@ -1,58 +1,63 @@
 # frozen_string_literal: true
 
 module Wallaby
-  # Cancancan base authorization provider
+  # @note This authorization provider DOES NOT use the existing
+  #   {https://www.rubydoc.info/github/CanCanCommunity/cancancan/CanCan%2FControllerAdditions:current_ability
+  #   current_ability} helper. It has its own version of {#ability} instance.
+  # {https://github.com/CanCanCommunity/cancancan CanCanCan} base authorization provider.
   class CancancanAuthorizationProvider < ModelAuthorizationProvider
-    # Detect and see if Cancancan is in use.
-    # @param context [ActionController::Base]
-    # @return [true] if Cancancan is in use.
-    # @return [false] if Cancancan is not in use.
+    # Detect and see if CanCanCan is in use.
+    # @param context [ActionController::Base, ActionView::Base]
+    # @return [true] if CanCanCan is in use
+    # @return [false] otherwise.
     def self.available?(context)
-      defined?(CanCanCan) && defined?(Ability) && context.respond_to?(:current_ability)
+      defined?(CanCanCan) && context.respond_to?(:current_ability)
     end
 
-    # This will pull out the args required for contruction from context
-    # @param context [ActionController::Base]
-    # @return [Hash] args for initialize
-    def self.args_from(context)
-      { ability: context.current_ability, user: ModuleUtils.try_to(context, :current_user) }
-    end
+    # @!attribute [w] ability
+    attr_writer :ability
 
     # @!attribute [r] ability
-    # @return [Ability]
-    attr_reader :ability
-
-    def initialize(ability:, user: nil)
-      @ability = ability
-      @user = user
+    # @return [Ability] the Ability instance for {#user #user} (which is a
+    #   {Wallaby::AuthenticationConcern#wallaby_user #wallaby_user})
+    def ability
+      # NOTE: use current_ability's class to create the ability instance.
+      # just in case that developer uses a different Ability class (e.g. UserAbility)
+      @ability ||= options[:ability] || Ability.new(user)
+    rescue ArgumentError, NameError
+      context.current_ability
     end
 
     # Check user's permission for an action on given subject.
-    # This method will be used in controller.
+    #
+    # This method will be mostly used in controller.
     # @param action [Symbol, String]
     # @param subject [Object, Class]
     # @raise [Wallaby::Forbidden] when user is not authorized to perform the action.
     def authorize(action, subject)
       ability.authorize! action, subject
     rescue ::CanCan::AccessDenied
-      Logger.info Locale.t('errors.unauthorized', user: user, action: action, subject: subject)
+      Logger.error <<~MESSAGE
+        #{Utils.inspect user} is forbidden to perform #{action} on #{Utils.inspect subject}
+      MESSAGE
       raise Forbidden
     end
 
     # Check and see if user is allowed to perform an action on given subject.
     # @param action [Symbol, String]
     # @param subject [Object, Class]
-    # @return [Boolean]
+    # @return [true] if user is allowed to perform the action
+    # @return [false] otherwise
     def authorized?(action, subject)
       ability.can? action, subject
     end
 
-    # Restrict user to access certain scope.
+    # Restrict user to access certain scope/query.
     # @param action [Symbol, String]
     # @param scope [Object]
     # @return [Object]
     def accessible_for(action, scope)
-      ModuleUtils.try_to(scope, :accessible_by, ability, action) || scope
+      scope.try(:accessible_by, ability, action) || scope
     end
 
     # @!method attributes_for(action, subject)
@@ -62,7 +67,7 @@ module Wallaby
     # @return nil
     delegate :attributes_for, to: :ability
 
-    # Just return nil
+    # Simply return nil as CanCanCan doesn't provide such a feature.
     # @param action [Symbol, String]
     # @param subject [Object]
     # @return [nil]

data/lib/authorizers/wallaby/default_authorization_provider.rb

@@ -1,20 +1,13 @@
 # frozen_string_literal: true
 
 module Wallaby
-  # Default authorization provider
+  # Default authorization provider that whitelists everything.
   class DefaultAuthorizationProvider < ModelAuthorizationProvider
-    # Always available.
-    # @param _context [ActionController::Base]
-    # @return [true]
+    # It returns false so that it can be used as the last resort.
+    # @param _context [ActionController::Base, ActionView::Base]
+    # @return [false]
     def self.available?(_context)
-      true
-    end
-
-    # This will pull out the args required for contruction from context
-    # @param _context [ActionController::Base]
-    # @return [Hash] args for initialize
-    def self.args_from(_context)
-      {}
+      false
     end
 
     # Do nothing
@@ -47,7 +40,7 @@ module Wallaby
       {}
     end
 
-    # @note Please make sure to return nil when the authorization doesn't support this feature.
+    # @note Please make sure to return nil when the authorization provider doesn't support this feature.
     # @param _action [Symbol, String]
     # @param _subject [Object]
     # @return [nil]

data/lib/authorizers/wallaby/model_authorizer.rb

@@ -1,68 +1,29 @@
 # frozen_string_literal: true
 
 module Wallaby
-  # Model Authorizer to provide authorization functions
-  # @since 5.2.0
+  # This is the base authorizer class to provider authorization for given/associated model.
+  #
+  # For best practice, please create an application authorizer class (see example)
+  # to better control the functions shared between different model authorizers.
+  # @example Create an application class for Admin Interface usage
+  #   class Admin::ApplicationAuthorizer < Wallaby::ModelAuthorizer
+  #     base_class!
+  #   end
+  # @since wallaby-5.2.0
   class ModelAuthorizer
     extend Baseable::ClassMethods
+    base_class!
 
     class << self
-      # @!attribute [w] model_class
-      attr_writer :model_class
-
-      # @!attribute [r] model_class
-      # Return associated model class, e.g. return **Product** for **ProductAuthorizer**.
-      #
-      # If Wallaby can't recognise the model class for Authorizer, it's required to be configured as below example:
-      # @example To configure model class
-      #   class Admin::ProductAuthorizer < Admin::ApplicationAuthorizer
-      #     self.model_class = Product
-      #   end
-      # @example To configure model class for version below 5.2.0
-      #   class Admin::ProductAuthorizer < Admin::ApplicationAuthorizer
-      #     def self.model_class
-      #       Product
-      #     end
-      #   end
-      # @return [Class] assoicated model class
-      # @return [nil] if current class is marked as base class
-      # @return [nil] if current class is the same as the value of {Wallaby::Configuration::Mapping#model_authorizer}
-      # @return [nil] if current class is {Wallaby::ModelAuthorizer}
-      # @return [nil] if assoicated model class is not found
-      def model_class
-        return unless self < ModelAuthorizer
-        return if base_class? || self == Wallaby.configuration.mapping.model_authorizer
-
-        @model_class ||= Map.model_class_map(name.gsub(/(^#{namespace}::)|(Authorizer$)/, EMPTY_STRING))
-      end
-
       # @!attribute [w] provider_name
       attr_writer :provider_name
 
       # @!attribute [r] provider_name
-      # @return [String, Symbol] provider name of the authorization framework used
+      # Provider name of the authorization framework used.
+      # It will be inherited from its parent classes if there isn't one for current class.
+      # @return [String, Symbol]
       def provider_name
-        @provider_name ||= ModuleUtils.try_to superclass, :provider_name
-      end
-
-      # Factory method to create the model authorizer
-      # @param context [ActionController::Base]
-      # @param model_class [Class]
-      # @return [Wallaby::ModelAuthorizer]
-      def create(context, model_class)
-        model_class ||= self.model_class
-        provider_class = guess_provider_class context, model_class
-        new model_class, provider_class, provider_class.args_from(context)
-      end
-
-      private
-
-      # @param context [ActionController::Base]
-      # @param model_class [Class]
-      # @return [Class] provider class
-      def guess_provider_class(context, model_class)
-        providers = Map.authorizer_provider_map model_class
-        providers[provider_name] || providers.values.find { |klass| klass.available? context }
+        @provider_name ||= superclass.try :provider_name
       end
     end
 
@@ -73,28 +34,43 @@ module Wallaby
     attr_reader :model_class
 
     # @!attribute [r] provider
-    # @return [Wallaby::ModelAuthorizationProvider]
-    # @since 5.2.0
+    # @return [Wallaby::ModelAuthorizationProvider] the instance that does the job
+    # @since wallaby-5.2.0
     attr_reader :provider
 
+    # @!attribute [r] context
+    # @return [ActionController::Base, ActionView::Base]
+    # @since 0.2.2
+    attr_reader :context
+
+    # @!attribute [r] options
+    # @return [Hash]
+    # @since 0.2.2
+    attr_reader :options
+
     # @param model_class [Class]
-    # @param provider_name_or_class [String, Symbol, Class]
-    # @param options [Hash]
-    def initialize(model_class, provider_name_or_class, options = {})
+    # @param context [ActionController::Base, ActionView::Base]
+    # @param options [Symbol, String, nil]
+    def initialize(model_class, context, **options)
       @model_class = model_class || self.class.model_class
-      @provider = init_provider provider_name_or_class, options
+      @context = context
+      @options = options
+      @provider = guess_provider_from(context)
     end
 
     protected
 
-    # Go through provider list and detect which provider is used.
-    # @param provider_name_or_class [String, Symbol, Class]
-    # @param options [Hash]
-    # @return [Wallaby::Authorizer]
-    def init_provider(provider_name_or_class, options)
-      providers = Map.authorizer_provider_map model_class
-      provider_class = provider_name_or_class.is_a?(Class) ? provider_name_or_class : providers[provider_name_or_class]
-      provider_class.new(**options)
+    # Go through the provider list and find out the one is
+    # {Wallaby::ModelAuthorizationProvider.available? .available?}
+    # @param context [ActionController::Base, ActionView::Base]
+    def guess_provider_from(context)
+      provider_class =
+        Map.authorizer_provider_map(model_class).try do |providers|
+          providers[options[:provider_name] || self.class.provider_name] \
+            || providers.values.find { |klass| klass.available? context } \
+            || providers[:default] # fallback to default
+        end
+      provider_class.new context, options
     end
   end
 end