pragma-operation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7fcd5701aaa0aa49b20295bd71d6ddc588497703
+  data.tar.gz: 93ba0c1bc4babd8702c1cf60157ed2ea9d9ec0fd
+SHA512:
+  metadata.gz: 0ef5a8d2a21ec06508545284dd72d51fe9a4a964b3003bb188def99b642a4c0f06213f308fbb69c4e0460f2eab33f36171e79b3d46d574829d0bfdb48315e937
+  data.tar.gz: 02c4231ed617768e829dc551c3e7d40e1da8aca12808d2f6c7813ffdf124a8216662bc847f83fd3b642211b30ec86c0e09671864c49aa35f5c25010787dd81bc

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/pkg/
+/spec/reports/
+/tmp/
+/spec/examples.txt

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,87 @@
+require: rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 2.3
+  Include:
+    - '**/Gemfile'
+    - '**/Rakefile'
+  Exclude:
+   - 'bin/*'
+   - 'db/**/*'
+   - 'vendor/bundle/**/*'
+   - 'spec/spec_helper.rb'
+   - 'spec/rails_helper.rb'
+   - 'spec/support/**/*'
+   - 'config/**/*'
+   - '**/Rakefile'
+   - '**/Gemfile'
+
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/requests/**/*'
+
+Style/BlockDelimiters:
+  Exclude:
+    - 'spec/**/*'
+
+Style/AlignParameters:
+  EnforcedStyle: with_fixed_indentation
+
+Style/ClosingParenthesisIndentation:
+  Enabled: false
+
+Metrics/LineLength:
+  Max: 100
+  AllowURI: true
+
+Style/FirstParameterIndentation:
+  Enabled: false
+
+Style/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Style/IndentArray:
+  EnforcedStyle: consistent
+
+Style/IndentHash:
+  EnforcedStyle: consistent
+
+Style/SignalException:
+  EnforcedStyle: semantic
+
+Style/BracesAroundHashParameters:
+  EnforcedStyle: context_dependent
+
+Lint/EndAlignment:
+  AlignWith: variable
+  AutoCorrect: true
+
+Style/AndOr:
+  EnforcedStyle: conditionals
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+RSpec/NamedSubject:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+Style/MultilineMethodCallBraceLayout:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.1
+before_install: gem install bundler -v 1.13.3

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in pragma-operation.gemspec
+gemspec
+
+gem 'pragma-policy', github: 'pragmarb/pragma-policy'
+gem 'pragma-contract', github: 'pragmarb/pragma-contract'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Alessandro Desantis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,43 @@
+# Pragma::Operation
+
+[![Build Status](https://img.shields.io/travis/pragmarb/pragma-operation.svg?maxAge=3600&style=flat-square)](https://travis-ci.org/pragmarb/pragma-operation)
+[![Dependency Status](https://img.shields.io/gemnasium/pragmarb/pragma-operation.svg?maxAge=3600&style=flat-square)](https://gemnasium.com/github.com/pragmarb/pragma-operation)
+[![Code Climate](https://img.shields.io/codeclimate/github/pragmarb/pragma-operation.svg?maxAge=3600&style=flat-square)](https://codeclimate.com/github/pragmarb/pragma-operation)
+[![Coveralls](https://img.shields.io/coveralls/pragmarb/pragma-operation.svg?maxAge=3600&style=flat-square)](https://coveralls.io/github/pragmarb/pragma-operation)
+
+Operations encapsulate the business logic of your JSON API.
+
+They are built on top of the awesome [Interactor](https://github.com/collectiveidea/interactor) gem.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pragma-operation'
+```
+
+And then execute:
+
+```console
+$ bundle
+```
+
+Or install it yourself as:
+
+```console
+$ gem install pragma-operation
+```
+
+## Usage
+
+All documentation is in the [doc](https://github.com/pragmarb/pragma-operation/tree/master/doc)
+folder.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/pragmarb/pragma-operation.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "pragma/operation"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/doc/01-basic-usage.md

@@ -0,0 +1,145 @@
+# 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
+            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.
+
+## 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
+```

data/doc/02-contracts.md

@@ -0,0 +1,92 @@
+# Contracts
+
+Operations integrate with [Pragma::Contract](https://github.com/pragmarb/pragma-contract). You can
+specify the contract to use with `#contract` and get access to `#validate` and `#validate!` in your
+operations:
+
+```ruby
+module API
+  module V1
+    module Post
+      module Operation
+        class Create < Pragma::Operation::Base
+          contract API::V1::Post::Contract::Create
+
+          def call
+            post = Post.new
+
+            validate! contract
+            contract.save
+
+            respond_with status: :created, resource: post
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+If the contract passes validation, then all is good. If not, an error is raised:
+
+```ruby
+result1 = API::V1::Post::Operation::Create.call(params: {
+  title: 'My First Post',
+  body: 'Hello everyone, this is my first post!'
+})
+
+result1.status # => :created
+result1.resource
+# => {
+#      'title' => 'My First Post'
+#      'body' => 'Hello everyone, this is my first post!'
+#    }
+
+result2 = API::V1::Post::Operation::Create.call(params: {
+  title: 'My First Post'
+})
+
+result2.status # => :forbidden
+result2.resource
+# => {
+#      'error_type' => 'unprocessable_entity',
+#      'error_message' => 'The contract for this operation was not respected.',
+#      'meta' => {
+#        'errors' => {
+#          'body' => ["can't be blank"]
+#        }
+#      }
+#    }
+```
+
+You can also use the non-bang method `#validate` to implement your own logic:
+
+```ruby
+module API
+  module V1
+    module Post
+      module Operation
+        class Create < Pragma::Operation::Base
+          contract API::V1::Post::Contract::Create
+
+          def call
+            post = Post.new
+            contract = build_contract(post)
+
+            unless validate(contract)
+              respond_with!(
+                status: :unprocessable_entity,
+                resource: nil
+              )
+            end
+
+            contract.save
+
+            respond_with status: :created, resource: post
+          end
+        end
+      end
+    end
+  end
+end
+```

data/doc/03-policies.md

@@ -0,0 +1,94 @@
+# Policies
+
+Operations integrate with [Pragma::Policy](https://github.com/pragmarb/pragma-policy). All you have
+to do is specify the policy class with `#policy`. This will give you access to `#authorize` and
+`#authorize!`:
+
+```ruby
+module API
+  module V1
+    module Post
+      module Operation
+        class Create < Pragma::Operation::Base
+          policy API::V1::Post::Policy
+
+          def call
+            post = Post.new(params)
+            authorize! post
+
+            post.save!
+
+            respond_with status: :created, resource: post
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+Of course, you will now have to pass the user performing the operation in addition to the usual
+parameters:
+
+```ruby
+result1 = API::V1::Post::Operation::Create.call(
+  params: {
+    title: 'My First Post',
+    body: 'Hello everyone, this is my first post!'
+  },
+  current_user: authorized_user
+)
+
+result1.status # => :created
+result1.resource
+# => {
+#      'title' => 'My First Post'
+#      'body' => 'Hello everyone, this is my first post!'
+#    }
+
+result2 = API::V1::Post::Operation::Create.call(
+  params: {
+    title: 'My First Post',
+    body: 'Hello everyone, this is my first post!'
+  },
+  current_user: unauthorized_user
+)
+
+result2.status # => :forbidden
+result2.resource
+# => {
+#      'error_type' => 'forbidden',
+#      'error_message' => 'You are not authorized to perform this operation.'
+#    }
+```
+
+If you want to customize how you handle authorization, you can use the non-bang method `#authorize`:
+
+```ruby
+module API
+  module V1
+    module Post
+      module Operation
+        class Create < Pragma::Operation::Base
+          policy API::V1::Post::Policy
+
+          def call
+            post = Post.new(params)
+
+            unless authorize(post)
+              respond_with!(
+                status: :forbidden,
+                resource: nil # if you don't need error info
+              )
+            end
+
+            post.save!
+
+            respond_with status: :created, resource: post
+          end
+        end
+      end
+    end
+  end
+end
+```

data/lib/pragma/operation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+require 'interactor'
+
+require 'pragma/operation/version'
+require 'pragma/operation/base'
+require 'pragma/operation/authorization'
+require 'pragma/operation/validation'
+
+module Pragma
+  # Operations provide business logic encapsulation for your JSON API.
+  #
+  # @author Alessandro Desantis
+  module Operation
+  end
+end

data/lib/pragma/operation/authorization.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+module Pragma
+  module Operation
+    module Authorization
+      def self.included(base)
+        base.extend ClassMethods
+        base.include InstanceMethods
+      end
+
+      module ClassMethods
+        # Sets the contract to use for validating this operation.
+        #
+        # @param klass [Class] a subclass of +Pragma::Contract::Base+
+        def contract(klass)
+          @contract = klass
+        end
+
+        # Builds the contract for the given resource, using the previous defined contract class.
+        #
+        # @param resource [Object]
+        #
+        # @return [Pragma::Contract::Base]
+        #
+        # @see #contract
+        def build_contract(resource)
+          @contract.new(resource)
+        end
+      end
+
+      module InstanceMethods
+        # Builds the policy for the current user and the given resource, using the previously
+        # defined policy class.
+        #
+        # @param resource [Object]
+        #
+        # @return [Pragma::Policy::Base]
+        #
+        # @see .policy
+        # @see .build_policy
+        def build_policy(resource)
+          self.class.build_policy(user: current_user, resource: resource)
+        end
+
+        # Authorizes this operation on the provided resource or policy.
+        #
+        # @param authorizable [Pragma::Policy::Base|Object] resource or policy
+        #
+        # @return [Boolean] whether the operation is authorized
+        def authorize(authorizable)
+          policy = if defined?(Pragma::Policy::Base) && authorizable.is_a?(Pragma::Policy::Base)
+            authorizable
+          else
+            build_policy(authorizable)
+          end
+
+          policy.send("#{self.class.operation_name}?")
+        end
+
+        # Authorizes this operation on the provided resource or policy. If the user is not
+        # authorized to perform the operation, responds with 403 Forbidden and an error body and
+        # halts the execution.
+        #
+        # @param authorizable [Pragma::Policy::Base|Object] resource or policy
+        def authorize!(authorizable)
+          return if authorize(authorizable)
+
+          respond_with!(
+            status: :forbidden,
+            resource: {
+              error_type: :forbidden,
+              error_message: 'You are not authorized to perform this operation.'
+            }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/pragma/operation/base.rb

@@ -0,0 +1,237 @@
+# 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
+
+      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 << self
+        def inherited(child)
+          child.class_eval do
+            include Authorization
+            include Validation
+
+            before :setup_context
+            around :handle_halt
+            after :mark_result, :consolidate_status, :validate_status, :set_default_status
+          end
+        end
+
+        # Returns the name of this operation.
+        #
+        # For instance, if the operation is called +API::V1::Post::Operation::Create+, returns
+        # +create+.
+        #
+        # @return [Symbol]
+        def operation_name
+          name.split('::').last
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .tr('-', '_')
+            .downcase
+            .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+ 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+
+      def respond_with(status:, resource:)
+        context.status = status
+        context.resource = resource
+      end
+
+      # Same as {#respond_with}, but also halts the execution of the operation.
+      #
+      # @param status [Integer|Symbol] an HTTP status code
+      # @param resource [Object] an object responding to +#to_json+
+      #
+      # @see #respond_with
+      def respond_with!(status:, resource:)
+        respond_with status: status, resource: resource
+        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
+
+      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 ||= {}
+      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!
+      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

data/lib/pragma/operation/validation.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+module Pragma
+  module Operation
+    module Validation
+      def self.included(base)
+        base.extend ClassMethods
+        base.include InstanceMethods
+      end
+
+      module ClassMethods
+        # Sets the policy to use for authorizing this operation.
+        #
+        # @param klass [Class] a subclass of +Pragma::Policy::Base+
+        def policy(klass)
+          @policy = klass
+        end
+
+        # Builds the policy for the given user and resource, using the previous defined policy
+        # class.
+        #
+        # @param user [Object]
+        # @param resource [Object]
+        #
+        # @return [Pragma::Policy::Base]
+        #
+        # @see #policy
+        def build_policy(user:, resource:)
+          @policy.new(user: user, resource: resource)
+        end
+      end
+
+      module InstanceMethods
+        # Builds the contract for the given resource, using the previously defined contract class.
+        #
+        # This is just an instance-level alias of {.build_contract}. You should use this from inside
+        # the operation.
+        #
+        # @param resource [Object]
+        #
+        # @return [Pragma::Contract::Base]
+        #
+        # @see .contract
+        # @see .build_contract
+        def build_contract(resource)
+          self.class.build_contract(resource)
+        end
+
+        # Validates this operation on the provided contract or resource.
+        #
+        # @param validatable [Object|Pragma::Contract::Base] contract or resource
+        #
+        # @return [Boolean] whether the operation is valid
+        def validate(validatable)
+          contract = if defined?(Pragma::Contract::Base) && validatable.is_a?(Pragma::Contract::Base)
+            validatable
+          else
+            build_contract(validatable)
+          end
+
+          contract.validate(params)
+        end
+
+        # Validates this operation on the provided contract or resource. If the operation is not
+        # valid, responds with 422 Unprocessable Entity and an error body and halts the execution.
+        #
+        # @param validatable [Object|Pragma::Contract::Base] contract or resource
+        def validate!(validatable)
+          contract = if defined?(Pragma::Contract::Base) && validatable.is_a?(Pragma::Contract::Base)
+            validatable
+          else
+            build_contract(validatable)
+          end
+
+          return if validate(contract)
+
+          respond_with!(
+            status: :unprocessable_entity,
+            resource: {
+              error_type: :contract_not_respected,
+              error_message: 'The contract for this operation was not respected.',
+              meta: {
+                errors: contract.errors.messages
+              }
+            }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/pragma/operation/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+module Pragma
+  module Operation
+    VERSION = '0.1.0'
+  end
+end

data/pragma-operation.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+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.version       = Pragma::Operation::VERSION
+  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.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  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.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

@@ -0,0 +1,161 @@
+--- !ruby/object:Gem::Specification
+name: pragma-operation
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alessandro Desantis
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-12-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: interactor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.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: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- desa.alessandro@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- doc/01-basic-usage.md
+- doc/02-contracts.md
+- doc/03-policies.md
+- lib/pragma/operation.rb
+- lib/pragma/operation/authorization.rb
+- lib/pragma/operation/base.rb
+- lib/pragma/operation/validation.rb
+- lib/pragma/operation/version.rb
+- pragma-operation.gemspec
+homepage: https://github.com/pragmarb/pragma-operation
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2
+signing_key: 
+specification_version: 4
+summary: Business logic encapsulation for your JSON API.
+test_files: []