blacksheep 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e39f0b5524839016bc9a6811e51257f49a2d5f00cf42d3d9fe07ab01de6b602
-  data.tar.gz: c0d169df550b722a11ffa2aaf7ea0ef5657f3c64ad5f7b8b6ac2c10419ba7ef0
+  metadata.gz: 75dfef125950bec755e918dba9e56bf6877ab8a3baedc2e42d16b62e31aa395c
+  data.tar.gz: 4ef04a290cd93670d126e910022cada3a16bb446af06eb26e759073c87e2a3b6
 SHA512:
-  metadata.gz: 589637c6979dbaebe1756f95ebe0038a7b707059b4a809f56d1d6575bbd4b5e2f8822bb54815e93491f0517b22a71ccb06d690da05b5396ea30fbe6c9acabb59
-  data.tar.gz: b12064a64112255dc2b75aacf1a3ff2245131c96ccd5a12a863242e5642c10d97096f19010981c97b53940a905988bffd04508d77f337846e24dded666e874de
+  metadata.gz: '0084555561e9b92801cf7524379c6e3523eda987a612beb869f8be81abf69c4ebba673ebf609c1310074f7f2d65c954998061cb70701e1052a6efb6507431eeb'
+  data.tar.gz: d5e729097addb0df435e051c8289de2e8c0ca06d1d17d1690c630ab251a657d169719b5dc70cde2744537aac5f0cf544d9ee05d2596668151ff306609d5054b2

data/README.md

@@ -22,7 +22,108 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### 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:
+
+  * #perform, and…
+  * #call
+
+`#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`
+
+
+```ruby
+##perform sample
+action_result = Blacksheep::Action.new.perform(params) do |params|
+  # do somethin with the params that return a `Blacksheep::ActionResult`
+end
+
+##perform 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. It more interesting to modifiy the action with decorators such as:
+
+  * `JsonTransformer`
+  * `Localizer`
+  * `DefaultErrorHandler`
+  * `ResultMatcher`
+
+The decaorators can be configured globaly 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 a JsonResultObject 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)`.
+
+
+#### 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.
+
+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.
+
+```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 check for status :ok in sucess 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/lib/blacksheep.rb

@@ -1,6 +1,5 @@
 require "blacksheep/version"
-require "blacksheep/json_meta"
-require "blacksheep/json_result"
+require "blacksheep/action_result"
 require "blacksheep/action_decorator"
 require "blacksheep/decorators/default_error_handler"
 require "blacksheep/decorators/json_transformer"

data/lib/blacksheep/action.rb

@@ -57,8 +57,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/{json_result.rb → action_result.rb}

@@ -1,15 +1,15 @@
 module Blacksheep
-  class JsonResult
+  class ActionResult
 
-    attr_reader :json, :status
+    attr_reader :data, :status
 
-    def initialize(json, status)
-      @json = json
+    def initialize(data, status)
+      @data = data
       @status = status
     end
 
-    def set_json(value)
-      @json = value
+    def set_data(value)
+      @data = value
 
       self
     end
@@ -24,9 +24,9 @@ module Blacksheep
       @status == :ok
     end
 
-    def render(json_wrap: 'data')
+    def render_json(json_wrap: 'data')
       {
-        json:   wrap(json, json_wrap: json_wrap),
+        json:   wrap(@data, json_wrap: json_wrap),
         status: status
       }
     end

data/lib/blacksheep/decorators/default_error_handler.rb

@@ -2,19 +2,7 @@ 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
@@ -78,7 +66,7 @@ module Blacksheep
         }
         status = :internal_server_error # 500
 
-        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
+    # @class Blacksheep::Decorators::ErrorHandler
+    class 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

@@ -6,7 +6,6 @@ module Blacksheep
       attr_reader :case, :params
 
       def call(params, **options)
-        puts transformer: "*" * 50
         detect_case(params)
 
         transformed_params = self.transformed_params(params)
@@ -15,7 +14,7 @@ module Blacksheep
 
         transformed_json = transform_result(json)
 
-        JsonResult.new(transformed_json, :ok)
+        ActionResult.new(transformed_json, :ok)
       end
 
       def perform(params, current_user: nil, **options, &block)
@@ -26,7 +25,7 @@ module Blacksheep
         json = block.call(transformed_params)
         transformed_json = transform_result(json)
 
-        JsonResult.new(transformed_json, :ok)
+        ActionResult.new(transformed_json, :ok)
       end
 
 
@@ -42,7 +41,7 @@ module Blacksheep
           when 'camel'
             snakecase_keys(params)
           else
-            raise Blackseep::Error, "unknown_case #{@case}"
+            raise Blacksheep::Error, "unknown_case #{@case}"
         end
       end
 
@@ -54,14 +53,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/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.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: blacksheep
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Martin Schweizer
@@ -87,12 +87,12 @@ files:
 - lib/blacksheep.rb
 - lib/blacksheep/action.rb
 - lib/blacksheep/action_decorator.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:

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