blacksheep 0.1.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e39f0b5524839016bc9a6811e51257f49a2d5f00cf42d3d9fe07ab01de6b602
-  data.tar.gz: c0d169df550b722a11ffa2aaf7ea0ef5657f3c64ad5f7b8b6ac2c10419ba7ef0
+  metadata.gz: 7e104e67c03822bfb437736bf0beb1dca0cb9c4ced32a3027c359193cf730573
+  data.tar.gz: 6bff8f6260ab533267122865740890643bc1cd2e59870cfb48bc85c47fb8a8d3
 SHA512:
-  metadata.gz: 589637c6979dbaebe1756f95ebe0038a7b707059b4a809f56d1d6575bbd4b5e2f8822bb54815e93491f0517b22a71ccb06d690da05b5396ea30fbe6c9acabb59
-  data.tar.gz: b12064a64112255dc2b75aacf1a3ff2245131c96ccd5a12a863242e5642c10d97096f19010981c97b53940a905988bffd04508d77f337846e24dded666e874de
+  metadata.gz: 34aed33d507dec1a11a3b372bb8fcb5cc5d824ea213e512ef2b5ecc27f5e89cb3550d1c1b6e6d0a02c7a4bd380a103373ad30e4a4317d48cc75287633be22ba5
+  data.tar.gz: 3b95215a11cc3f7937f3db323de40596d15839adc87e644eb2cf7a99e79f621c687faa45f4b62446212280e3b13b8750951147e29968018a69b55da446ff3861

data/Gemfile.lock

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

data/README.md

@@ -22,7 +22,108 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Actions
+
+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 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`. When using the `ResultMatcher` decorator a block can be used for result matching.
+
+
+```ruby
+#perform sample
+action_result = Blacksheep::Action.new.perform(params) do |params|
+  # do somethin with the params that return a `Blacksheep::ActionResult`
+end
+
+#call sample
+action_result = MyAction.new.call(params, current_user: current_user)
+```
+
+`Blacksheeep::ActionResult` has a data and a status attribute. In case of json api actions its expected to store a json response into the data attribute, and the respective http status into the status attribute.
+
+
+### Decorators
+
+This alone does not give any benefit. Modifying the action with decorators adds additional functionality:
+
+  * `JsonTransformer`
+  * `Localizer`
+  * `DefaultErrorHandler`
+  * `ResultMatcher`
+
+The decaorators can be configured globally by defining them in an initializer.
+
+```ruby
+# Defining decorator wheras innermost is first
+Blacksheep::Action.add_decorator(Blacksheep::Decorators::Localizer)
+Blacksheep::Action.add_decorator(Blacksheep::Decorators::DefaultErrorHandler)
+Blacksheep::Action.add_decorator(Blacksheep::Decorators::JsonTransformer)
+Blacksheep::Action.add_decorator(Blacksheep::Decorators::ResultMatcher)
+```
+
+#### Blacksheep::Decorators::Localizer
+
+A localizer sets the I18n locale when passed in a request parameter named `_locale`.
+
+
+#### Blacksheep::Decorators::DefaultErrorHandler
+
+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)
+  json = {
+    errors: [
+      pointer: {
+        source: 'Internal'
+      },
+      title: "#{exception.class}",
+      detail: "#{exception.message}",
+    ]
+  }
+  status = :internal_server_error # 500
+
+  ActionResult.new(json, status)
+end
+```
+
+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 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 `ResultMatcher` decorator enables to write a matcher block such as…
+
+```ruby
+MyAction.new.call(params) do |m|
+  m.success do |action_result|
+    # do something in success case
+  end
+  m.failure :unauthorized do |action_result|
+    # special handling for unauthorized access
+  end
+  m.failure do |v|
+    # any other failure
+  end
+end
+```
+
+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
 
@@ -30,6 +131,11 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+```
+gem build blacksheep
+gem push blacksheep-0.x.y.gem
+``
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/verticonaut/blacksheep.

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,10 +1,12 @@
 require "blacksheep/version"
-require "blacksheep/json_meta"
-require "blacksheep/json_result"
+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|
@@ -57,8 +62,8 @@ module Blacksheep
       block.call(params)
     end
 
-    def json_result(json, status: :ok)
-      JsonResult.new(json, status)
+    def action_result(data, status: :ok)
+      ActionResult.new(data, status)
     end
 
   end

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,15 @@
+module Blacksheep
+  #
+  # @class Blacksheep::ActionError
+  class ActionError < StandardError
+    attr_reader :identifier, :title
+
+    def initialize(message, title: 'Error', identifier: 'undefined')
+      @identifier = identifier
+      @title = title
+
+      super(message)
+    end
+
+  end
+end

data/lib/blacksheep/action_result.rb

@@ -0,0 +1,70 @@
+module Blacksheep
+  class ActionResult
+
+    attr_reader :data, :status
+
+    def initialize(data, status)
+      @data = data
+      @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
+
+      self
+    end
+
+    def set_status(value)
+      @status = value
+
+      self
+    end
+
+    def success?
+      @status == :ok
+    end
+
+    def render_json(json_wrap: 'data')
+      {
+        json:   wrap(@data, json_wrap: json_wrap),
+        status: status
+      }
+    end
+
+    private
+
+    def wrap(json, json_wrap:)
+      wrap = success? ? json_wrap : nil
+
+      wrap.present? ? { wrap => json } : json
+    end
+
+  end
+end

data/lib/blacksheep/decorators/default_error_handler.rb

@@ -2,83 +2,61 @@ module Blacksheep
   module Decorators
     # @class Blacksheep::Decorators::DefaultErrorHandler
     class DefaultErrorHandler < ActionDecorator
-
-      def call(*)
-        puts error_handler: "*" * 50
-        super
-      rescue => exception
-        handle(exception)
-      end
-
-      def perform(*)
-        super
-      rescue => exception
-        handle(exception)
-      end
+      include ErrorHandler
 
       def handle(exception)
-        json = status = nil
+        json = nil
+        status = :internal_server_error
+
+        case exception
+          when Blacksheep::ActionError
+            json = {
+              errors: [
+                pointer: {
+                  source:  exception.backtrace.first,
+                  identifier: exception.identifier,
+                },
+                title: exception.title,
+                detail: exception.message,
+              ]
+            }
 
-        # 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
+            #   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
 
-        json = {
-          errors: [
-            pointer: {
-              source: 'Internal'
-            },
-            title: "#{exception.class}",
-            detail: "#{exception.message}",
-          ]
-        }
-        status = :internal_server_error # 500
+          else
+            json = {
+              errors: [
+                pointer: {
+                  source: 'Internal'
+                },
+                title: "#{exception.class}",
+                detail: "#{exception.message}",
+              ]
+            }
+        end
 
-        JsonResult.new(json, status)
+        ActionResult.new(json, status)
       end
 
       # def not_authorized_pointer(exception)

data/lib/blacksheep/decorators/error_handler.rb

@@ -0,0 +1,24 @@
+module Blacksheep
+  module Decorators
+    # @module Blacksheep::Decorators::ErrorHandler
+    module ErrorHandler
+
+      def call(*)
+        super
+      rescue => exception
+        handle(exception)
+      end
+
+      def perform(*)
+        super
+      rescue => exception
+        handle(exception)
+      end
+
+      def handle(exception)
+        raise Blacksheep::Error, 'Subclass responsibility'
+      end
+
+    end
+  end
+end

data/lib/blacksheep/decorators/json_transformer.rb

@@ -5,28 +5,28 @@ module Blacksheep
 
       attr_reader :case, :params
 
-      def call(params, **options)
-        puts transformer: "*" * 50
+      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)
 
         transformed_json = transform_result(json)
 
-        JsonResult.new(transformed_json, :ok)
+        ActionResult.new(transformed_json, :ok)
       end
 
       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)
 
-        JsonResult.new(transformed_json, :ok)
+        ActionResult.new(transformed_json, :ok)
       end
 
 
@@ -35,14 +35,14 @@ 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
           when 'camel'
             snakecase_keys(params)
           else
-            raise Blackseep::Error, "unknown_case #{@case}"
+            raise Blacksheep::Error, "unknown_case #{@case}"
         end
       end
 
@@ -54,14 +54,22 @@ module Blacksheep
       # @return [Array, Hash] The rsult structure with keys converted to source caseing
       # @see #camelize_keys
       def transform_result(obj)
-        case @case
+        is_action_result, data = if obj.kind_of?(Blacksheep::ActionResult)
+          [ true, obj.data ]
+        else
+          [ false, obj ]
+        end
+
+        converted_data = case @case
           when 'snake', 'as_is'
-            obj
+            data
           when 'camel'
-            camelize_keys(obj)
+            camelize_keys(data)
           else
-            raise Blackseep::Error, "unknown_case #{@case}"
+            raise Blacksheep::Error, "unknown_case #{@case}"
         end
+
+        is_action_result ? obj.set_data(converted_data) : converted_data
       end
 
       #

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/decorators/result_matcher.rb

@@ -5,19 +5,19 @@ module Blacksheep
     # @class Blacksheep::Decorators::ResultMatcher
     class ResultMatcher < ActionDecorator
       Matcher = -> {
-        # Match `json_result` with status :ok for success
-        success_case = Dry::Matcher::Case.new do |json_result, _|
-          if json_result.success?
-            json_result
+        # Match `action_result` with status :ok for success
+        success_case = Dry::Matcher::Case.new do |action_result, _|
+          if action_result.success?
+            action_result
           else
             # this is a constant from dry/core/constants
             Dry::Matcher::Undefined
           end
         end
 
-        # Match `json_result` with status not :ok` for failure - other status' can be distinguished
-        failure_case = Dry::Matcher::Case.new do |json_result, patterns|
-          if !json_result.success! && (patterns.empty? || patterns.include?(json_result.status))
+        # Match `action_result` with status not :ok` for failure - other status' can be distinguished
+        failure_case = Dry::Matcher::Case.new do |action_result, patterns|
+          if !action_result.success! && (patterns.empty? || patterns.include?(action_result.status))
             value
           else
             Dry::Matcher::Undefined
@@ -31,12 +31,11 @@ module Blacksheep
       include Dry::Matcher.for(:call, with: Matcher)
 
       def call(*)
-        puts matcher: "*" * 50
         super
       end
 
       def perform(*)
-        raise Blackseep::Error, 'JsonResultMatcher does not support #perform'
+        raise Blacksheep::Error, 'ResultMatcher does not support #perform'
       end
 
     end

data/lib/blacksheep/version.rb

@@ -1,3 +1,3 @@
 module Blacksheep
-  VERSION = "0.1.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: blacksheep
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Martin Schweizer
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-05-17 00:00:00.000000000 Z
+date: 2021-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-matcher
@@ -87,18 +87,20 @@ 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
 - lib/blacksheep/decorators/json_transformer.rb
 - lib/blacksheep/decorators/localizer.rb
 - lib/blacksheep/decorators/result_matcher.rb
-- lib/blacksheep/json_meta.rb
-- lib/blacksheep/json_result.rb
 - lib/blacksheep/version.rb
 homepage: http://verticonaut.me
 licenses:
 - MIT
 metadata:
   homepage_uri: http://verticonaut.me
+  source_code_uri: https://github.com/verticonaut/blacksheep
 post_install_message:
 rdoc_options: []
 require_paths:

data/lib/blacksheep/json_meta.rb

@@ -1,41 +0,0 @@
-module Blacksheep
-  class JsonMeta
-
-    attr_reader :json
-
-    def initialize(json = {})
-      @json = json
-    end
-
-    class << self
-      def success(title: nil, detail: nil)
-        new.success(title: title, detail: detail)
-      end
-    end
-
-    def success(title: nil, detail: nil)
-      result = {
-        success: true,
-      }
-
-      if title.present?
-        result[:title] = title
-      elsif detail.present?
-        result[:title] = 'Success'
-      end
-
-      result[:detail] = detail if detail.present?
-
-      json[:result] = result
-
-      self
-    end
-
-    def as_json
-      {
-        jsonMeta: json
-      }
-    end
-
-  end
-end

data/lib/blacksheep/json_result.rb

@@ -1,43 +0,0 @@
-module Blacksheep
-  class JsonResult
-
-    attr_reader :json, :status
-
-    def initialize(json, status)
-      @json = json
-      @status = status
-    end
-
-    def set_json(value)
-      @json = value
-
-      self
-    end
-
-    def set_status(value)
-      @status = value
-
-      self
-    end
-
-    def success?
-      @status == :ok
-    end
-
-    def render(json_wrap: 'data')
-      {
-        json:   wrap(json, json_wrap: json_wrap),
-        status: status
-      }
-    end
-
-    private
-
-    def wrap(json, json_wrap:)
-      wrap = success? ? json_wrap : nil
-
-      wrap.present? ? { wrap => json } : json
-    end
-
-  end
-end