pragma-operation 1.6.3 → 2.0.0

data/lib/pragma/operation/error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Operation
+    class Error
+      attr_reader :error_type, :error_message, :meta
+
+      def initialize(error_type:, error_message:, meta: {})
+        @error_type = error_type
+        @error_message = error_message
+        @meta = meta
+      end
+
+      def as_json
+        {
+          error_type: error_type,
+          error_message: error_message,
+          meta: meta
+        }
+      end
+
+      def to_json
+        JSON.dump as_json
+      end
+    end
+  end
+end

data/lib/pragma/operation/response.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Operation
+    class Response
+      STATUSES = {
+        100 => :continue,
+        101 => :switching_protocols,
+        102 => :processing,
+        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
+
+      attr_accessor :entity, :headers
+      attr_reader :status
+
+      def initialize(status: 200, entity: nil, headers: {})
+        self.status = status
+        self.entity = entity
+        self.headers = headers
+      end
+
+      def success?
+        %w[1 2 3].include?(@status.to_s[0])
+      end
+
+      def failure?
+        !success?
+      end
+
+      def status=(v)
+        case v
+        when Integer
+          fail ArgumentError, "#{v} is not a valid status code" unless STATUSES[v]
+          @status = v
+        when Symbol, String
+          fail ArgumentError, "#{v} is not a valid status phrase" unless STATUSES.invert[v.to_sym]
+          @status = STATUSES.invert[v.to_sym]
+        end
+      end
+
+      def decorate_with(decorator)
+        tap do
+          self.entity = decorator.represent(entity)
+        end
+      end
+    end
+  end
+end

data/lib/pragma/operation/response/bad_request.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Operation
+    class Response
+      class BadRequest < Response
+        def initialize(
+          entity: Error.new(error_type: :bad_request, error_message: 'This request is malformed.'),
+          headers: {}
+        )
+          super(status: 400, entity: entity, headers: headers)
+        end
+      end
+    end
+  end
+end

data/lib/pragma/operation/response/created.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Operation
+    class Response
+      class Created < Response
+        def initialize(entity: nil, headers: {})
+          super(status: 201, entity: entity, headers: headers)
+        end
+      end
+    end
+  end
+end

data/lib/pragma/operation/response/forbidden.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Operation
+    class Response
+      class Forbidden < Response
+        def initialize(
+          entity: Error.new(
+            error_type: :forbidden,
+            error_message: 'You are not authorized to access the requested resource.'
+          ),
+          headers: {}
+        )
+          super(status: 403, entity: entity, headers: headers)
+        end
+      end
+    end
+  end
+end

data/lib/pragma/operation/response/no_content.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Operation
+    class Response
+      class NoContent < Response
+        def initialize(headers: {})
+          super(status: 204, entity: nil, headers: headers)
+        end
+      end
+    end
+  end
+end

data/lib/pragma/operation/response/not_found.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Operation
+    class Response
+      class NotFound < Response
+        def initialize(
+          entity: Error.new(
+            error_type: :not_found,
+            error_message: 'The requested resource could not be found.'
+          ),
+          headers: {}
+        )
+          super(status: 404, entity: entity, headers: headers)
+        end
+      end
+    end
+  end
+end

data/lib/pragma/operation/response/ok.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Operation
+    class Response
+      class Ok < Response
+        def initialize(entity: nil, headers: {})
+          super(status: 200, entity: entity, headers: headers)
+        end
+      end
+    end
+  end
+end

data/lib/pragma/operation/response/unprocessable_entity.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Operation
+    class Response
+      class UnprocessableEntity < Response
+        def initialize(entity: nil, headers: {}, errors: nil)
+          fail ArgumentError, 'You cannot provide both :entity and :errors!' if entity && errors
+
+          entity ||= Error.new(
+            error_type: :unprocessable_entity,
+            error_message: 'The provided resource is in an unexpected format.',
+            meta: {
+              errors: errors || {}
+            }
+          )
+
+          super(status: 422, entity: entity, headers: headers)
+        end
+      end
+    end
+  end
+end

data/lib/pragma/operation/version.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
+
 module Pragma
   module Operation
-    VERSION = '1.6.3'
+    VERSION = '2.0.0'
   end
 end

data/pragma-operation.gemspec

@@ -1,35 +1,32 @@
-# coding: utf-8
+# frozen_string_literal: true
+
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'pragma/operation/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "pragma-operation"
+  spec.name          = 'pragma-operation'
   spec.version       = Pragma::Operation::VERSION
-  spec.authors       = ["Alessandro Desantis"]
-  spec.email         = ["desa.alessandro@gmail.com"]
+  spec.authors       = ['Alessandro Desantis']
+  spec.email         = ['desa.alessandro@gmail.com']
 
   spec.summary       = 'Business logic encapsulation for your JSON API.'
-  spec.homepage      = "https://github.com/pragmarb/pragma-operation"
-  spec.license       = "MIT"
+  spec.homepage      = 'https://github.com/pragmarb/pragma-operation'
+  spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  spec.add_dependency 'interactor', '~> 3.1.0'
+  spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'pragma-policy', '~> 0.1.0'
-  spec.add_development_dependency 'pragma-contract', '~> 0.1.0'
-  spec.add_development_dependency 'pragma-decorator', '~> 0.1.0'
+  spec.add_dependency 'trailblazer-operation', '~> 0.0'
 
-  spec.add_development_dependency "bundler"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "rspec"
-  spec.add_development_dependency "rubocop"
-  spec.add_development_dependency "rubocop-rspec"
-  spec.add_development_dependency "coveralls"
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'coveralls'
 end

metadata

@@ -1,71 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: pragma-operation
 version: !ruby/object:Gem::Version
-  version: 1.6.3
+  version: 2.0.0
 platform: ruby
 authors:
 - Alessandro Desantis
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-05-27 00:00:00.000000000 Z
+date: 2017-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: interactor
+  name: trailblazer-operation
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.1.0
+        version: '0.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.1.0
-- !ruby/object:Gem::Dependency
-  name: pragma-policy
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.0
-- !ruby/object:Gem::Dependency
-  name: pragma-contract
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.0
-- !ruby/object:Gem::Dependency
-  name: pragma-decorator
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: '0.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -167,15 +125,17 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
-- doc/01-basic-usage.md
-- doc/02-contracts.md
-- doc/03-policies.md
-- doc/04-decorators.md
 - lib/pragma/operation.rb
-- lib/pragma/operation/authorization.rb
 - lib/pragma/operation/base.rb
-- lib/pragma/operation/decoration.rb
-- lib/pragma/operation/validation.rb
+- lib/pragma/operation/error.rb
+- lib/pragma/operation/response.rb
+- lib/pragma/operation/response/bad_request.rb
+- lib/pragma/operation/response/created.rb
+- lib/pragma/operation/response/forbidden.rb
+- lib/pragma/operation/response/no_content.rb
+- lib/pragma/operation/response/not_found.rb
+- lib/pragma/operation/response/ok.rb
+- lib/pragma/operation/response/unprocessable_entity.rb
 - lib/pragma/operation/version.rb
 - pragma-operation.gemspec
 homepage: https://github.com/pragmarb/pragma-operation
@@ -198,7 +158,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.8
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: Business logic encapsulation for your JSON API.

data/doc/01-basic-usage.md

@@ -1,264 +0,0 @@
-# Basic usage
-
-Here's the simplest operation you can write:
-
-```ruby
-module API
-  module V1
-    module Ping
-      module Operation
-        class Create < Pragma::Operation::Base
-          def call
-            # The `status` parameter is optional (the default is `:ok`).
-            respond_with(
-              status: :ok,
-              resource: { pong: params[:pong] }
-            )
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-Here's how you use it:
-
-```ruby
-result = API::V1::Ping::Operation::Create.call(params: { pong: 'HELLO' })
-
-result.status # => :ok
-result.resource # => { pong: 'HELLO' }
-```
-
-As you can see, an operation takes parameters as input and responds with:
-
-- an HTTP status code;
-- (optional) a resource (i.e. an object implementing `#to_json`).
-
-If you don't want to return a resource, you can use the `#head` shortcut:
-
-```ruby
-module API
-  module V1
-    module Ping
-      module Operation
-        class Create < Pragma::Operation::Base
-          def call
-            head :no_content
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-Since Pragma::Operation is built on top of [Interactor](https://github.com/collectiveidea/interactor),
-you should consult its documentation for the basic usage of operations; the rest of this section
-only covers the features provided specifically by Pragma::Operation.
-
-## Headers
-
-You can attach headers to your response by manipulating the `headers` hash:
-
-```ruby
-module API
-  module V1
-    module Post
-      module Operation
-        class Create < Pragma::Operation::Base
-          def call
-            post = ::Post.new(params)
-            post.save!
-
-            headers['X-Post-Id'] = post.id
-
-            respond_with status: :created, resource: post
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-You can also set headers when calling `#respond_with`:
-
-```ruby
-module API
-  module V1
-    module Post
-      module Operation
-        class Create < Pragma::Operation::Base
-          def call
-            post = ::Post.new(params)
-            post.save!
-
-            respond_with status: :created, resource: post, headers: {
-              'X-Post-Id' => post.id
-            }
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-## HATEOAS
-
-Pragma::Operation supports HATEOAS by allowing you to specify a list of links to use for building
-the `Link` header. You can set the links by manipulating the `links` hash.
-
-For instance, here's how you could link to a post's comments and author:
-
-```ruby
-module API
-  module V1
-    module Post
-      module Operation
-        class Show < Pragma::Operation::Base
-          def call
-            post = ::Post.find(params[:id])
-
-            links['comments'] = "/posts/#{post.id}/comments"
-            links['author'] = "/users/#{post.author.id}"
-
-            respond_with resource: post
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-You can also set the links when calling `#respond_with`:
-
-```ruby
-module API
-  module V1
-    module Post
-      module Operation
-        class Show < Pragma::Operation::Base
-          def call
-            post = ::Post.find(params[:id])
-
-            respond_with resource: post, links: {
-              comments: "/posts/#{post.id}/comments",
-              author: "/users/#{post.author.id}"
-            }
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-This will build the `Link` header accordingly:
-
-```ruby
-result = API::V1::Post::Operation::Show.call(params: { id: 1 })
-
-result.status # => :ok
-result.headers
-# => {
-#   'Link' => '</posts/1/comments>; rel="comments",
-#                </users/49>; rel="author"'
-#    }
-```
-
-**Note: Do not set the `Link` header manually, as it will be replaced when building links from the
-`links` hash.**
-
-## Handling errors
-
-You can use the `#success?` and `#failure?` method to check whether an operation was successful. An
-operation is considered successful when it returns a 2xx or 3xx status code:
-
-```ruby
-module API
-  module V1
-    module Ping
-      module Operation
-        class Create < Pragma::Operation::Base
-          def call
-            if params[:pong].blank?
-              return respond_with(
-                status: :unprocessable_entity,
-                resource: {
-                  error_type: :missing_pong,
-                  error_message: "You must provide a 'pong' parameter."
-                }
-              )
-            end
-
-            respond_with status: :ok, resource: { pong: params[:pong] }
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-Once more, here's an example usage of the above operation:
-
-```ruby
-result1 = API::V1::Ping::Operation::Create.call(params: { pong: '' })
-result1.success? # => false
-
-result2 = API::V1::Ping::Operation::Create.call(params: { pong: 'HELLO' })
-result2.success? # => true
-```
-
-## Halting the execution
-
-Both `#respond_with` and `#head` provide bang counterparts that halt the execution of the operation.
-They are useful, for instance, in before callbacks.
-
-The above operation can be rewritten like this:
-
-```ruby
-module API
-  module V1
-    module Ping
-      module Operation
-        class Create < Pragma::Operation::Base
-          before :validate_params
-
-          def call
-            respond_with status: :ok, resource: { pong: params[:pong] }
-          end
-
-          private
-
-          def validate_params
-            if params[:pong].blank?
-              respond_with!(
-                status: :unprocessable_entity,
-                resource: {
-                  error_type: :missing_pong,
-                  error_message: "You must provide a 'pong' parameter."
-                }
-              )
-            end
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-The result is identical:
-
-```ruby
-result1 = API::V1::Ping::Operation::Create.call(params: { pong: '' })
-result1.success? # => false
-
-result2 = API::V1::Ping::Operation::Create.call(params: { pong: 'HELLO' })
-result2.success? # => true
-```