pragma-operation 1.6.3 → 2.0.0

data/doc/02-contracts.md

@@ -1,154 +0,0 @@
-# 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
-```
-
-You can also pass a block to compute the contract class dynamically. If the block returns `nil`,
-validation will be skipped:
-
-```ruby
-module API
-  module V1
-    module Post
-      module Operation
-        class Create < Pragma::Operation::Base
-          contract do |context|
-            # ...
-          end
-
-          def call
-            # ...
-          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
-```
-
-If you want to run some logic after validation, you can override the `#after_validation` method
-in your operation. It takes the result of the validation as its first argument:
-
-```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
-
-          protected
-
-          def after_validation(result)
-            # ...
-          end
-        end
-      end
-    end
-  end
-end
-```

data/doc/03-policies.md

@@ -1,179 +0,0 @@
-# Policies
-
-Operations integrate with [Pragma::Policy](https://github.com/pragmarb/pragma-policy). All you have
-to do is specify the policy class with `#policy`:
-
-```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
-```
-
-You can also pass a block to compute the policy class dynamically. If the block returns `nil`,
-authorization will be skipped:
-
-```ruby
-module API
-  module V1
-    module Post
-      module Operation
-        class Create < Pragma::Operation::Base
-          policy do |context|
-            # ...
-          end
-
-          def call
-            # ...
-          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
-```
-
-If you want to run some logic after authorization, you can override the `#after_authorization` method
-in your operation. It takes the result of the authorization as its first argument:
-
-```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
-
-          protected
-
-          def after_authorization(result)
-            # ...
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-## Authorizing collections
-
-To authorize a collection, use `#authorize_collection`. This will call `.accessible_by` on the
-policy class with the current user and the provided collection and return an authorized collection
-containing only records accessible by the user.
-
-```ruby
-module API
-  module V1
-    module Post
-      module Operation
-        class Index < Pragma::Operation::Base
-          policy API::V1::Post::Policy
-
-          def call
-            posts = authorize_collection Post.all
-            respond_with status: :ok, resource: posts
-          end
-        end
-      end
-    end
-  end
-end
-```

data/doc/04-decorators.md

@@ -1,50 +0,0 @@
-# Decorators
-
-Operations integrate with [Pragma::Decorator](https://github.com/pragmarb/pragma-decorator). All you
-have to do is specify the decorator class with `#decorator`. This will give you access to
-`#decorate`:
-
-```ruby
-module API
-  module V1
-    module Post
-      module Operation
-        class Show < Pragma::Operation::Base
-          decorator API::V1::Post::Decorator
-
-          def call
-            post = Post.find(params[:id])
-            respond_with status: :ok, resource: decorate(post)
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-You can also pass a block to compute the decorator class dynamically. If the block returns `nil`,
-decoration will be skipped:
-
-```ruby
-module API
-  module V1
-    module Post
-      module Operation
-        class Show < Pragma::Operation::Base
-          decorator do |context|
-            # ...
-          end
-
-          def call
-            # ...
-          end
-        end
-      end
-    end
-  end
-end
-```
-
-Note that `#decorate` works with both singular resources and collections, as it uses the decorator's
-[`.represent`](http://trailblazer.to/gems/representable/3.0/api.html) method.

data/lib/pragma/operation/authorization.rb

@@ -1,130 +0,0 @@
-# frozen_string_literal: true
-module Pragma
-  module Operation
-    # Provides integration with {https://github.com/pragmarb/pragma-policy Pragma::Policy}.
-    #
-    # @author Alessandro Desantis
-    module Authorization
-      def self.included(base)
-        base.extend ClassMethods
-        base.include InstanceMethods
-      end
-
-      module ClassMethods # :nodoc:
-        # Sets the policy to use for authorizing this operation.
-        #
-        # @param klass [Class] a subclass of +Pragma::Policy::Base+
-        #
-        # @yield A block which will be called with the operation's context which should return
-        #   the policy class. The block can also return +nil+ if authorization should be skipped.
-        def policy(klass = nil, &block)
-          if !klass && !block_given?
-            fail ArgumentError, 'You must pass either a policy class or a block'
-          end
-
-          @policy = klass || block
-        end
-
-        # Returns the policy class.
-        #
-        # @return [Class]
-        def policy_klass
-          @policy
-        end
-      end
-
-      module InstanceMethods # :nodoc:
-        # 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)
-          policy_klass = compute_policy_klass
-          return resource unless policy_klass
-
-          policy_klass.new(user: current_user, resource: resource)
-        end
-
-        # Authorizes this operation on the provided resource or policy.
-        #
-        # If no policy was defined, simply returns true.
-        #
-        # @param authorizable [Pragma::Policy::Base|Object] resource or policy
-        #
-        # @return [Boolean] whether the operation is authorized
-        def authorize(authorizable)
-          return true unless compute_policy_klass
-
-          # rubocop:disable Metrics/LineLength
-          policy = if Object.const_defined?('Pragma::Policy::Base') && authorizable.is_a?(Pragma::Policy::Base)
-            authorizable
-          else
-            build_policy(authorizable)
-          end
-          # rubocop:enable Metrics/LineLength
-
-          if Object.const_defined?('Pragma::Contract::Base') && authorizable.is_a?(Pragma::Contract::Base)
-            authorizable.deserialize(params)
-          end
-
-          policy.send("#{self.class.operation_name}?").tap do |result|
-            after_authorization result
-          end
-        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
-
-        # Runs after authorization is done.
-        #
-        # @param result [Boolean] the result of the authorization
-        def after_authorization(result)
-        end
-
-        # Scopes the provided collection.
-        #
-        # If no policy class is defined, simply returns the collection.
-        #
-        # @param collection [Enumerable]
-        #
-        # @return [Pragma::Decorator::Base|Enumerable]
-        def authorize_collection(collection)
-          policy_klass = compute_policy_klass
-          return collection unless policy_klass
-
-          policy_klass.accessible_by(
-            user: current_user,
-            scope: collection
-          )
-        end
-
-        def compute_policy_klass
-          if self.class.policy_klass.is_a?(Proc)
-            self.class.policy_klass.call(context)
-          else
-            self.class.policy_klass
-          end
-        end
-      end
-    end
-  end
-end