blacksheep 0.2.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75dfef125950bec755e918dba9e56bf6877ab8a3baedc2e42d16b62e31aa395c
-  data.tar.gz: 4ef04a290cd93670d126e910022cada3a16bb446af06eb26e759073c87e2a3b6
+  metadata.gz: f5e427c080e5f5eaf01f76d9436ff18a36e183318acb2b942105566b34be7c03
+  data.tar.gz: 22221c3900e3dd7d09c796e15e14d765c07cd307add2bbb39696b0767a17f088
 SHA512:
-  metadata.gz: '0084555561e9b92801cf7524379c6e3523eda987a612beb869f8be81abf69c4ebba673ebf609c1310074f7f2d65c954998061cb70701e1052a6efb6507431eeb'
-  data.tar.gz: d5e729097addb0df435e051c8289de2e8c0ca06d1d17d1690c630ab251a657d169719b5dc70cde2744537aac5f0cf544d9ee05d2596668151ff306609d5054b2
+  metadata.gz: cf17a2e2d7732162e0578567d8f04206da221f63d766294670c8b549126e24dd43d5a56451eabb4af6a8a37889ea4aa483a9c77b85c85b38308aec6fe76550c0
+  data.tar.gz: 02cfecdffd2c6d09c3dca2440b6f130e33ae564ab6ba06ba729733f1c2bcc0d9c6605e8db2ef86e307cce4f7bc9250da0f133cb24551b2ad32337ac7d1e23f54

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    blacksheep (0.1.0)
+    blacksheep (0.3.2)
       dry-matcher
 
 GEM
@@ -38,4 +38,4 @@ DEPENDENCIES
   rspec (~> 3.0)
 
 BUNDLED WITH
-   1.17.2
+   1.17.3

data/README.md

@@ -24,24 +24,24 @@ Or install it yourself as:
 
 ### Actions
 
-Core if blacksheep is the Blacksheep::Action. It provides basic fuctionality to handle rest API actions - but can handle other actions as well. The core methods of Actions are:
+Core of blacksheep is the `Blacksheep::Action`. It provides basic functionality to handle rest API actions - but can handle other actions as well. The core methods of actions are:
 
-  * #perform, and…
-  * #call
+  * #perform with a block that implements the action
+  * #call on an action instance for processing and a potential block for result matching (see dcorators below).
 
 `#perform` takes a block that is executed with the params passed. #perform has the following api:
   `#perform(params, current_user: (default to nil), **options)`
 
-`#call` can be used when a Blacksheep::Action is sublassed as an action processing its opertation in a call method with the same signature of `#perform`
+`#call` can be used when a Blacksheep::Action is sublassed as an action processing its opertation in a call method with the same signature of `#perform`. When using the `ResultMatcher` decorator a block can be used for result matching.
 
 
 ```ruby
-##perform sample
+#perform sample
 action_result = Blacksheep::Action.new.perform(params) do |params|
   # do somethin with the params that return a `Blacksheep::ActionResult`
 end
 
-##perform sample
+#call sample
 action_result = MyAction.new.call(params, current_user: current_user)
 ```
 
@@ -50,14 +50,14 @@ action_result = MyAction.new.call(params, current_user: current_user)
 
 ### Decorators
 
-This alone does not give any benefit. It more interesting to modifiy the action with decorators such as:
+This alone does not give any benefit. Modifying the action with decorators adds additional functionality:
 
   * `JsonTransformer`
   * `Localizer`
   * `DefaultErrorHandler`
   * `ResultMatcher`
 
-The decaorators can be configured globaly by defining them in an initializer.
+The decaorators can be configured globally by defining them in an initializer.
 
 ```ruby
 # Defining decorator wheras innermost is first
@@ -74,7 +74,7 @@ A localizer sets the I18n locale when passed in a request parameter named `_loca
 
 #### Blacksheep::Decorators::DefaultErrorHandler
 
-A default error handler can be used in API opertions. The handler catches an error and returns a JsonResultObject such as
+A default error handler can be used in API opertions. The handler catches an error and returns an ActionResult such as…
 
 ```ruby
 def handle_exception(exception)
@@ -93,20 +93,20 @@ def handle_exception(exception)
 end
 ```
 
-You can write your own Errorhandler by including the module `Blacksheep::Decorators::ErrorHandler` and implementing the method `#handle(exception)`.
+You can write your own ErrorHandler by including the module `Blacksheep::Decorators::ErrorHandler` and implementing the method `#handle_exception(<Exception>)`.
 
 
 #### Blacksheep::Decorators::JsonTransformer
 
-Assuming the params is a json payload with a specific caseing (e.g. camelCase when used in a JS application such as vue) the JsonTransfomer takes the params and tranforms it's keys into snake_case as used in ruby often.
-The request has to define the case passed (and hence desired response casing) in the parameter `_case`. If the case is requests as `camel` then paramter keys are tranformed to `snake_case` before going into the action and are transformed back into CamelCase when leaving the operation.
+Assuming the params is a json payload with a specific caseing (e.g. camelCase when used in a JS application such as Vue) the JsonTransfomer takes the params and transforms it's keys into snake_case as used in ruby often.
+The request has to define the case passed (and hence desired response casing) in the parameter `_case`. If the case is requests as `camel` then parameter keys are transformed to `snake_case` before beeing passed into the action and are transformed back into CamelCase when leaving the operation.
 
 If JsonTransfomer is used the action should return a simple JSON structure which is transfformed and stored in an ActionResult.
 
 
 #### Blacksheep::Decorators::ResultMatcher
 
-This decorator can be used when implementing your own actions by subclassing `Blacksheep::Action` and using the  `#call` style for processing. Adding the matcher decorator enables to write a matchers such as e.g.
+This decorator can be used when implementing your own actions by subclassing `Blacksheep::Action` and using the  `#call` style for processing. Adding the `ResultMatcher` decorator enables to write a matcher block such as…
 
 ```ruby
 MyAction.new.call(params) do |m|
@@ -122,7 +122,7 @@ MyAction.new.call(params) do |m|
 end
 ```
 
-The action has to return a Blacksheep::ActionResult which is check for status :ok in sucess case and any other status in failure case.
+The action has to return a Blacksheep::ActionResult which is checked for status `:ok` for success case and any other status in failure case.
 
 
 ## Development
@@ -134,7 +134,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 ```
 gem build blacksheep
 gem push blacksheep-0.x.y.gem
-```
+``
 
 ## Contributing
 

data/blacksheep.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   # to allow pushing to a single host or delete this section to allow pushing to any host.
   if spec.respond_to?(:metadata)
     spec.metadata["homepage_uri"] = spec.homepage
-    # spec.metadata["source_code_uri"] = "Put your gem's public repo URL here."
+    spec.metadata["source_code_uri"] = "https://github.com/verticonaut/blacksheep"
     # spec.metadata["changelog_uri"] = "Put your gem's CHANGELOG.md URL here."
   else
     raise "RubyGems 2.0 or newer is required to protect against " \

data/lib/blacksheep.rb

@@ -1,9 +1,12 @@
 require "blacksheep/version"
 require "blacksheep/action_result"
+require "blacksheep/action_error"
 require "blacksheep/action_decorator"
+require "blacksheep/decorators/error_handler"
 require "blacksheep/decorators/default_error_handler"
 require "blacksheep/decorators/json_transformer"
 require "blacksheep/decorators/result_matcher"
+require "blacksheep/decorators/localizer"
 require "blacksheep/action"
 require "blacksheep/version"
 

data/lib/blacksheep/action.rb

@@ -28,11 +28,16 @@ module Blacksheep
         @@decorators ||= []
       end
 
+      #
+      # Adds a decorator to the list of decorated to be applied on Balcksheep::Actions
+      # @param decorator [type] [description]
+      #
+      # @return [type] [description]
       def add_decorator(decorator)
-        decorators << decorator
+        decorators << decorator unless decorators.include?(decorator)
       end
 
-      def new(*)
+      def new(*arguments, &block)
         instance = super
 
         decorators.each do |decorator|

data/lib/blacksheep/action_decorator.rb

@@ -1,9 +1,29 @@
 require 'delegate'
 
 module Blacksheep
+  # @class Blacksheep::ActionDecorator
   class ActionDecorator < SimpleDelegator
+
+    # Access to the decorators class - since original class is overwritten to return the model class.
+    #
+    # @return [Class] The class of the deocrator.
+    # @see [#class]
+    alias_method :__class__, :class
+
     def class
       __getobj__.class
     end
+
+    #
+    # Just for curiosity - get the decorators chain
+    #
+    # @return [type] [description]
+    def decorators_chain
+      decorated = __getobj__
+      chain = decorated.kind_of?(Blacksheep::ActionDecorator) ? decorated.decorators_chain : [ decorated.class ]
+
+      chain.unshift(self.__class__)
+    end
+
   end
 end

data/lib/blacksheep/action_error.rb

@@ -0,0 +1,16 @@
+module Blacksheep
+  #
+  # @class Blacksheep::ActionError
+  class ActionError < StandardError
+    attr_reader :identifier, :title
+
+    def initialize(message, title: 'Error', identifier: 'undefined', status: :internal_server_error)
+      @identifier = identifier
+      @title = title
+      @status = status
+
+      super(message)
+    end
+
+  end
+end

data/lib/blacksheep/action_result.rb

@@ -8,6 +8,33 @@ module Blacksheep
       @status = status
     end
 
+    class << self
+      def success(message)
+        json = {
+          _meta: {
+            message: message
+          }
+        }
+
+        new(json, :ok)
+      end
+
+      def error(title: 'Error', message:, status: :internal_server_error, pointer: 'unspecified')
+        json = {
+          errors: [
+            pointer: {
+              source: pointer
+            },
+            title: title,
+            detail: message,
+          ]
+        }
+        status = :internal_server_error
+
+        new(json, status)
+      end
+    end
+
     def set_data(value)
       @data = value
 

data/lib/blacksheep/decorators/default_error_handler.rb

@@ -7,64 +7,57 @@ module Blacksheep
       def handle(exception)
         json = status = nil
 
-        # case exception
-        #   when Exceptions::ValidationException
-        #     errors = []
-        #     exception.model.errors.each do |attribute, message|
-        #       errors << {
-        #         title:  "'#{attribute}' validation error",
-        #         detail: message,
-        #       }
-        #     end
-        #     json = {
-        #       errors: errors
-        #     }
-        #     status = :unprocessable_entity # 422
-        #   when Pundit::NotAuthorizedError
-        #     json = {
-        #       errors: [
-        #         pointer: {
-        #           source: not_authorized_pointer(exception)
-        #         },
-        #         title: "#{exception.class}",
-        #         detail: "#{exception.message}",
-        #       ]
-        #     }
-        #     status = :unauthorized # 401
-        #   when Exceptions::AuthenticationInvalid
-        #     json = {
-        #       errors: [
-        #         pointer: {
-        #           source: 'Secured Module'
-        #         },
-        #         title: "#{exception.class}",
-        #         detail: "#{exception.message}",
-        #       ]
-        #     }
-        #     status = :unauthorized # 401
-        #   else
-        #     json = {
-        #       errors: [
-        #         pointer: {
-        #           source: 'Internal'
-        #         },
-        #         title: "#{exception.class}",
-        #         detail: "#{exception.message}",
-        #       ]
-        #     }
-        #     status = :internal_server_error # 500
-        # end
+        case exception
+          when Blacksheep::ActionError
+            json = {
+              errors: [
+                pointer: {
+                  source:  exception.backtrace.first,
+                  identifier: exception.identifier,
+                },
+                title: exception.title,
+                detail: exception.message,
+              ]
+            }
 
-        json = {
-          errors: [
-            pointer: {
-              source: 'Internal'
-            },
-            title: "#{exception.class}",
-            detail: "#{exception.message}",
-          ]
-        }
-        status = :internal_server_error # 500
+            status = exception.status
+
+            #   when Pundit::NotAuthorizedError
+            #     json = {
+            #       errors: [
+            #         pointer: {
+            #           source: not_authorized_pointer(exception)
+            #         },
+            #         title: "#{exception.class}",
+            #         detail: "#{exception.message}",
+            #       ]
+            #     }
+            #     status = :unauthorized # 401
+            #   when Exceptions::AuthenticationInvalid
+            #     json = {
+            #       errors: [
+            #         pointer: {
+            #           source: 'Secured Module'
+            #         },
+            #         title: "#{exception.class}",
+            #         detail: "#{exception.message}",
+            #       ]
+            #     }
+            #     status = :unauthorized # 401
+
+          else
+            json = {
+              errors: [
+                pointer: {
+                  source: 'Internal'
+                },
+                title: "#{exception.class}",
+                detail: "#{exception.message}",
+              ]
+            }
+        end
+
+        status ||= :internal_server_error
 
         ActionResult.new(json, status)
       end

data/lib/blacksheep/decorators/error_handler.rb

@@ -1,7 +1,7 @@
 module Blacksheep
   module Decorators
-    # @class Blacksheep::Decorators::ErrorHandler
-    class ErrorHandler
+    # @module Blacksheep::Decorators::ErrorHandler
+    module ErrorHandler
 
       def call(*)
         super

data/lib/blacksheep/decorators/json_transformer.rb

@@ -5,10 +5,10 @@ module Blacksheep
 
       attr_reader :case, :params
 
-      def call(params, **options)
+      def call(params, current_user: nil, **options)
         detect_case(params)
 
-        transformed_params = self.transformed_params(params)
+        transformed_params = self.transform_params(params)
 
         json = super(transformed_params, **options)
 
@@ -20,9 +20,10 @@ module Blacksheep
       def perform(params, current_user: nil, **options, &block)
         detect_case(params)
 
-        transformed_params = self.transformed_params(params)
+        transformed_params = self.transform_params(params)
+
+        json = super(transformed_params, current_user: current_user, **options, &block)
 
-        json = block.call(transformed_params)
         transformed_json = transform_result(json)
 
         ActionResult.new(transformed_json, :ok)
@@ -34,7 +35,7 @@ module Blacksheep
       #
       # @return [Array, Hash] The params converted into snake_case
       # @see #snakecase_keys
-      def transformed_params(params)
+      def transform_params(params)
         case @case
           when 'snake', 'as_is'
             params

data/lib/blacksheep/decorators/localizer.rb

@@ -1,10 +1,10 @@
 module Blacksheep
   module Decorators
 
-    # @class Blacksheep::Decorators::Localozer
+    # @class Blacksheep::Decorators::Localizer
     class Localizer < ActionDecorator
 
-      def call(params, **)
+      def call(params, current_user: nil, **options)
         if (locale = params[:_locale])
           I18n.with_locale(locale) do
             super
@@ -14,7 +14,8 @@ module Blacksheep
         end
       end
 
-      def perform(params, **)
+      def perform(params, current_user: nil, **options)
+
         if (locale = params[:_locale])
           I18n.with_locale(locale) do
             super

data/lib/blacksheep/version.rb

@@ -1,3 +1,3 @@
 module Blacksheep
-  VERSION = "0.2.0"
+  VERSION = "0.3.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: blacksheep
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Martin Schweizer
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-05-17 00:00:00.000000000 Z
+date: 2021-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-matcher
@@ -87,6 +87,7 @@ files:
 - lib/blacksheep.rb
 - lib/blacksheep/action.rb
 - lib/blacksheep/action_decorator.rb
+- lib/blacksheep/action_error.rb
 - lib/blacksheep/action_result.rb
 - lib/blacksheep/decorators/default_error_handler.rb
 - lib/blacksheep/decorators/error_handler.rb
@@ -99,6 +100,7 @@ licenses:
 - MIT
 metadata:
   homepage_uri: http://verticonaut.me
+  source_code_uri: https://github.com/verticonaut/blacksheep
 post_install_message:
 rdoc_options: []
 require_paths: