pragma-operation 1.6.3 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 155c66fd00efabe09496be40e05ba3b2c93b5434
-  data.tar.gz: a724471382751d9e1d588f2cbdd8677c7489ee17
+  metadata.gz: b48bd839081e93bf86ae68587a35c6f3ad07fc4d
+  data.tar.gz: a0ce83bc5177c74503d82b744126f0f02931093c
 SHA512:
-  metadata.gz: 93a1c9a43f9e4750f0e9dbf53f69fdb1c3a480d0f09ba08730f6088cd6b3a31fcb16b82cb3c56071f47dfcfc23965c38826dd3bdc3f5cd229d6efc7ca71cc8eb
-  data.tar.gz: 3d640627d7f36be9a19891816085584f3d8f176098d12484d82cd4f0eb760f1d955f8b19053f8caf959d07013d84876a0cc1f09425561e25dd82bd5dce236c44
+  metadata.gz: cde98287cc82bc74923286973dc18cf83c04847943bc5bbc86652ac59b7391272b2b41a336cfbc47f2da9f3cc2dbf3c0f381a0dde76040a5a00d36d87848ca5d
+  data.tar.gz: 9d4179add815dcb6c5732c8c8501ba407298d97a1ac78c749e1499e85dede8a6b2d146c6e48e6db890df171f426f3a78e85469f2eed9aafe22f52b085245b015

data/.rubocop.yml

@@ -15,6 +15,7 @@ AllCops:
    - 'config/**/*'
    - '**/Rakefile'
    - '**/Gemfile'
+   - 'pragma-operation.gemspec'
 
 RSpec/DescribeClass:
   Exclude:
@@ -24,26 +25,26 @@ Style/BlockDelimiters:
   Exclude:
     - 'spec/**/*'
 
-Style/AlignParameters:
+Layout/AlignParameters:
   EnforcedStyle: with_fixed_indentation
 
-Style/ClosingParenthesisIndentation:
+Layout/ClosingParenthesisIndentation:
   Enabled: false
 
 Metrics/LineLength:
   Max: 100
   AllowURI: true
 
-Style/FirstParameterIndentation:
+Layout/FirstParameterIndentation:
   Enabled: false
 
-Style/MultilineMethodCallIndentation:
+Layout/MultilineMethodCallIndentation:
   EnforcedStyle: indented
 
-Style/IndentArray:
+Layout/IndentArray:
   EnforcedStyle: consistent
 
-Style/IndentHash:
+Layout/IndentHash:
   EnforcedStyle: consistent
 
 Style/SignalException:
@@ -68,7 +69,7 @@ RSpec/NamedSubject:
 RSpec/ExampleLength:
   Enabled: false
 
-Style/MultilineMethodCallBraceLayout:
+Layout/MultilineMethodCallBraceLayout:
   Enabled: false
 
 Metrics/MethodLength:
@@ -86,7 +87,7 @@ Metrics/CyclomaticComplexity:
 Metrics/ClassLength:
   Enabled: false
 
-Style/CaseIndentation:
+Layout/CaseIndentation:
   EnforcedStyle: end
   IndentOneStep: false
 

data/README.md

@@ -7,7 +7,7 @@
 
 Operations encapsulate the business logic of your JSON API.
 
-They are built on top of the awesome [Interactor](https://github.com/collectiveidea/interactor) gem.
+They are built on top of the [Trailblazer::Operation](https://github.com/trailblazer/trailblazer-operation) gem.
 
 ## Installation
 
@@ -31,8 +31,169 @@ $ gem install pragma-operation
 
 ## Usage
 
-All documentation is in the [doc](https://github.com/pragmarb/pragma-operation/tree/master/doc)
-folder.
+Let's build your first operation!
+
+```ruby
+module API
+  module V1
+    module Article
+      class Show < Pragma::Operation::Base
+        step :find!
+        failure :handle_not_found!, fail_fast: true
+        step :authorize!
+        failure :handle_unauthorized!
+        step :respond!
+
+        def find!(params:, **options)
+          options['model'] = ::Article.find_by(id: params[:id])
+        end
+
+        def handle_not_found!(options)
+          options['result.response'] = Pragma::Operation::Response::NotFound.new
+          false
+        end
+
+        def authorize!(options)
+          options['result.authorization'] = options['model'].published? || 
+            options['model'].author == options['current_user']
+        end
+
+        def handle_unauthorized!(options)
+          options['result.response'] = Pragma::Operation::Response::Forbidden.new(
+            entity: Error.new(
+              error_type: :forbidden,
+              error_message: 'You can only access an article if published or authored by you.'
+            )
+          )
+        end
+  
+        def respond!(options)
+          options['result.response'] = Pragma::Operation::Response::Ok.new(
+            entity: options['model'].as_json
+          )
+        end
+      end
+    end
+  end
+end
+```
+
+Yes, I know. This does not make any sense yet. Before continuing, I encourage you to read (and
+understand!) the documentation of [Trailblazer::Operation](http://trailblazer.to/gems/operation/2.0/index.html).
+Pragma::Operation is simply an extension of its TRB counterpart. For the rest of this guide, we will
+assume you have a good understanding of TRB concepts like flow control and macros.
+
+### Response basics
+
+The only requirement for a Pragma operation is that it sets a `result.response` key in the options
+hash by the end of its execution. This is a `Pragma::Operation::Response` object that will be used
+by [pragma-rails](https://github.com/pragmarb/pragma-rails) or another integration to respond with
+the proper HTTP information.
+
+Responses have, just as you'd expect, a status, headers and body. You can manipulate them by using
+the `status`, `headers` and `entity` parameters of the initializer:
+
+```ruby
+response = Pragma::Operation::Response.new(
+  status: 201,
+  headers: {
+    'X-Api-Custom' => 'Value'
+  },
+  entity: my_model
+)
+```
+
+You can also set these properties through their accessors after instantiating the response:
+
+```ruby
+# You can set the status as a symbol:
+response.status = :created
+
+# You can set it as an HTTP status code:
+response.status = 201
+
+# You can manipulate headers:
+response.headers['X-Api-Custom'] = 'Value'
+
+# You can manipulate the entity:
+response.entity = my_model
+
+# The entity can be any object responding to #to_json:
+response.entity = {
+  foo: :bar
+}
+```
+
+### Decorating entities
+
+The response class also has support for Pragma [decorators](https://github.com/pragmarb/pragma-decorator).
+
+If you use decorators, you can set a decorator as the entity or you can use the `#decorate_with`
+convenience method to decorate the existing entity:
+
+```ruby
+response.entity = ArticleDecorator.new(article)
+
+# This is equivalent to the above:
+response.entity = article
+response.decorate_with(ArticleDecorator) # returns the response itself for chaining
+```
+
+### Errors
+
+Pragma::Operation ships with an `Error` data structure that's simply the recommended way to present
+your errors. You can build your custom error by creating a new instance of it and specify a 
+machine-readable error type and a human-readable error message:
+
+```ruby
+error = Pragma::Operation::Error.new(
+  error_type: :invalid_date,
+  error_message: 'You have specified an invalid date in your request.'
+)
+
+error.as_json # => {:error_type=>:invalid_date, :error_message=>"You have specified an invalid date in your request.", :meta=>{}}
+error.to_json # => {"error_type":"invalid_date","error_message":"You have specified an invalid date in your request.","meta":{}} 
+```
+
+Do you see that `meta` property in the JSON representation of the error? You can use it to include
+additional metadata about the error. This is especially useful, for instance, with validation errors
+as you can include the exact fields and validation messages (which is exactly what Pragma does by
+default, by the way):
+
+```ruby
+error = Pragma::Operation::Error.new(
+  error_type: :invalid_date,
+  error_message: 'You have specified an invalid date in your request.',
+  meta: {
+    expected_format: 'YYYY-MM-DD'
+  }
+)
+
+error.as_json # => {:error_type=>:invalid_date, :error_message=>"You have specified an invalid date in your request.", :meta=>{:expected_format=>"YYYY-MM-DD"}}
+error.to_json # => {"error_type":"invalid_date","error_message":"You have specified an invalid date in your request.","meta":{"expected_format":"YYYY-MM-DD"}}
+```
+
+If you don't want to go with this format, you are free to implement your own error class, but it is
+not recommended, as the [built-in macros](https://github.com/pragmarb/pragma/tree/master/lib/pragma/operation/macro) 
+will use `Pragma::Operation::Error`.
+
+### Built-in responses
+
+Last but not least, as you have seen in the example operation, Pragma provides some 
+[built-in responses](https://github.com/pragmarb/pragma-operation/tree/master/lib/pragma/operation/response) 
+for common status codes and bodies. Some of these only have a status code while others (the error
+responses) also have a default entity attached to them. For instance, you can use `Pragma::Operation::Response::Forbidden`
+without specifying your own error type and message:
+
+```ruby
+response = Pragma::Operation::Response::Forbidden.new
+
+response.status # => 403
+response.entity.to_json # => {"error_type":"forbidden","error_message":"You are not authorized to access the requested resource.","meta":{}}
+```
+
+The built-in responses are not meant to be comprehensive and you will most likely have to implement
+your own. If you write some that you think could be useful, feel free to open a PR!
 
 ## Contributing
 

data/lib/pragma/operation.rb

@@ -1,11 +1,21 @@
 # frozen_string_literal: true
-require 'interactor'
+
+require 'json'
+
+require 'trailblazer/operation'
 
 require 'pragma/operation/version'
-require 'pragma/operation/authorization'
-require 'pragma/operation/validation'
-require 'pragma/operation/decoration'
 require 'pragma/operation/base'
+require 'pragma/operation/error'
+
+require 'pragma/operation/response'
+require 'pragma/operation/response/bad_request'
+require 'pragma/operation/response/not_found'
+require 'pragma/operation/response/forbidden'
+require 'pragma/operation/response/unprocessable_entity'
+require 'pragma/operation/response/created'
+require 'pragma/operation/response/ok'
+require 'pragma/operation/response/no_content'
 
 module Pragma
   # Operations provide business logic encapsulation for your JSON API.

data/lib/pragma/operation/base.rb

@@ -1,86 +1,12 @@
 # frozen_string_literal: true
+
 module Pragma
   module Operation
     # This is the base class all your operations should extend.
     #
     # @author Alessandro Desantis
-    #
-    # @abstract Subclass and override {#call} to implement an operation.
-    class Base
-      include Interactor
-
-      include Authorization
-      include Validation
-      include Decoration
-
-      STATUSES = {
-        200 => :ok,
-        201 => :created,
-        202 => :accepted,
-        203 => :non_authoritative_information,
-        204 => :no_content,
-        205 => :reset_content,
-        206 => :partial_content,
-        207 => :multi_status,
-        208 => :already_reported,
-        300 => :multiple_choices,
-        301 => :moved_permanently,
-        302 => :found,
-        303 => :see_other,
-        304 => :not_modified,
-        305 => :use_proxy,
-        307 => :temporary_redirect,
-        400 => :bad_request,
-        401 => :unauthorized,
-        402 => :payment_required,
-        403 => :forbidden,
-        404 => :not_found,
-        405 => :method_not_allowed,
-        406 => :not_acceptable,
-        407 => :proxy_authentication_required,
-        408 => :request_timeout,
-        409 => :conflict,
-        410 => :gone,
-        411 => :length_required,
-        412 => :precondition_failed,
-        413 => :request_entity_too_large,
-        414 => :request_uri_too_large,
-        415 => :unsupported_media_type,
-        416 => :request_range_not_satisfiable,
-        417 => :expectation_failed,
-        418 => :im_a_teapot,
-        422 => :unprocessable_entity,
-        423 => :locked,
-        424 => :failed_dependency,
-        425 => :unordered_collection,
-        426 => :upgrade_required,
-        428 => :precondition_required,
-        429 => :too_many_requests,
-        431 => :request_header_fields_too_large,
-        449 => :retry_with,
-        500 => :internal_server_error,
-        501 => :not_implemented,
-        502 => :bad_gateway,
-        503 => :service_unavailable,
-        504 => :gateway_timeout,
-        505 => :http_version_not_supported,
-        506 => :variant_also_negotiates,
-        507 => :insufficient_storage,
-        509 => :bandwidth_limit_exceeded,
-        510 => :not_extended,
-        511 => :network_authentication_required
-      }.freeze
-
+    class Base < Trailblazer::Operation
       class << self
-        def inherited(child)
-          child.class_eval do
-            before :setup_context
-            around :handle_halt
-            after :mark_result, :consolidate_status, :validate_status, :set_default_status
-            after :build_links
-          end
-        end
-
         # Returns the name of this operation.
         #
         # For instance, if the operation is called +API::V1::Post::Operation::Create+, returns
@@ -96,177 +22,6 @@ module Pragma
             .to_sym
         end
       end
-
-      # Runs the operation.
-      def call
-        fail NotImplementedError
-      end
-
-      protected
-
-      # Returns the params this operation is being run with.
-      #
-      # This is just a shortcut for +context.params+.
-      #
-      # @return [Hash]
-      def params
-        context.params
-      end
-
-      # Sets the status and resource to respond with.
-      #
-      # You can achieve the same result by setting +context.status+, +context.headers+ and
-      # +context.resource+ wherever you want in {#call}.
-      #
-      # Note that calling this method doesn't halt the execution of the operation and that this
-      # method can be called multiple times, overriding the previous context.
-      #
-      # @param status [Integer|Symbol] an HTTP status code
-      # @param resource [Object] an object responding to +#to_json+
-      # @param headers [Hash] HTTP headers
-      # @param links [Hash] links to use for building the +Link+ header
-      def respond_with(status: nil, resource: nil, headers: nil, links: nil)
-        context.status = status if status
-        context.resource = resource if resource
-        context.headers = headers if headers
-        context.links = links if links
-      end
-
-      # Same as {#respond_with}, but also halts the execution of the operation.
-      #
-      # @see #respond_with
-      def respond_with!(*args)
-        respond_with(*args)
-        fail Halt
-      end
-
-      # Sets the status to respond with.
-      #
-      # You can achieve the same result by setting +context.status+ wherever you want in {#call}.
-      #
-      # Note that calling this method doesn't halt the execution of the operation and that this
-      # method can be called multiple times, overriding the previous context.
-      #
-      # @param status [Integer|Symbol] an HTTP status code
-      def head(status)
-        context.status = status
-      end
-
-      # Same as {#head}, but also halts the execution of the operation.
-      #
-      # @param status [Integer|Symbol] an HTTP status code
-      #
-      # @see #head
-      def head!(status)
-        head status
-        fail Halt
-      end
-
-      # Returns the current user.
-      #
-      # This is just a shortcut for +context.current_user+.
-      #
-      # @return [Object]
-      def current_user
-        context.current_user
-      end
-
-      # Returns the headers we are responding with.
-      #
-      # This is just a shortcut for +context.headers+.
-      #
-      # @return [Hash]
-      def headers
-        context.headers
-      end
-
-      # Returns the links we are responding with.
-      #
-      # This is just a shotcut for +context.links+.
-      #
-      # @return [Hash]
-      def links
-        context.links
-      end
-
-      private
-
-      def with_hooks
-        # This overrides the default behavior, which is not to run after hooks if an exception is
-        # raised either in +#call+ or one of the before hooks. See:
-        # https://github.com/collectiveidea/interactor/blob/master/lib/interactor/hooks.rb#L210)
-        run_around_hooks do
-          begin
-            run_before_hooks
-            yield
-          ensure
-            run_after_hooks
-          end
-        end
-      end
-
-      def setup_context
-        context.params ||= {}
-        context.headers = {}
-        context.links = {}
-      end
-
-      def handle_halt(interactor)
-        interactor.call
-      rescue Halt # rubocop:disable Lint/HandleExceptions
-      end
-
-      def set_default_status
-        return if context.status
-        context.status = context.resource ? :ok : :no_content
-      end
-
-      def validate_status
-        if context.status.is_a?(Integer)
-          fail InvalidStatusError, context.status unless STATUSES.key?(context.status)
-        else
-          fail InvalidStatusError, context.status unless STATUSES.invert.key?(context.status.to_sym)
-        end
-      end
-
-      def consolidate_status
-        context.status = if context.status.is_a?(Integer)
-          STATUSES[context.status]
-        else
-          context.status.to_sym
-        end
-      end
-
-      def mark_result
-        return if /\A(2|3)\d{2}\z/ =~ STATUSES.invert[context.status].to_s
-        context.fail! pragma_operation_failure: true
-      end
-
-      def build_links
-        headers.delete('Link')
-
-        link_header = context.links.each_pair.select do |_relation, url|
-          url && !url.empty?
-        end.map do |relation, url|
-          %(<#{url}>; rel="#{relation}")
-        end.join(",\n  ")
-
-        headers['Link'] = link_header unless link_header.empty?
-      end
-    end
-
-    Halt = Class.new(StandardError)
-
-    # This error is raised when an invalid status is set for an operation.
-    #
-    # @author Alessandro Desantis
-    class InvalidStatusError < StandardError
-      # Initializes the error.
-      #
-      # @param [Integer|Symbol] an invalid HTTP status code
-      def initialize(status)
-        super "'#{status}' is not a valid HTTP status code."
-      end
     end
   end
 end