pragma-operation 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3420ea754f34bea0b246202e61f6aec0df6d32a5c0ec7898d44c7deea6839a62
-  data.tar.gz: 7791099085278d8dc3947222ab0cae339154b8ec56d3ce96512403031b18b37c
+  metadata.gz: 5d7f82fe38cc8a293b5ee3e99a22cf5fd700cdd24d5f2139c7e740414020fbb5
+  data.tar.gz: ca5b8bd2e1a558c1bb5874a4ed37b934fa8db6fda3e4b6346691e1a1fa857172
 SHA512:
-  metadata.gz: 0bf7cdd63680130290bc38bdaea3b33c971a98bfcb06f8c059d0e5d686bc50733454f4cf68e8e1b91f1ba3e19f2dda61cf790bcaeb30473b8b57bb4cb34a02d6
-  data.tar.gz: a3583c074377ed6739c27346a9746a6ac3cf389be390d348b0f91f2becf622b572c73a89d802ef74cbdade59edc61e50d4df0e0e8674b34af84d18de527f79f8
+  metadata.gz: 5976f017a997c16fdafc2051d82b5856d995403926f170ac9fdf004863f00dfb1164e718f461dab3d3607a295a9db451108f02a526b5df397322102709c060e4
+  data.tar.gz: f4b48e76ee2fb71e677ff1b110f94d8b37d2fe0f4c3e9dddecba2e535a1a32433fd2dec1ecfbc296f4dbcd265654e00a4fae2f832e76e94b1e6fa60ac07e7291

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## [2.2.0]
+
+### Added
+
+- Added `Conflict` response template
+
 ## [2.1.0]
 
 ### Added
@@ -24,6 +30,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 First Pragma 2 release.
 
-[Unreleased]: https://github.com/pragmarb/pragma-operation/compare/v2.1.0...HEAD
+[Unreleased]: https://github.com/pragmarb/pragma-operation/compare/v2.2.0...HEAD
+[2.2.0]: https://github.com/pragmarb/pragma-operation/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/pragmarb/pragma-operation/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/pragmarb/pragma-operation/compare/v1.6.3...v2.0.0

data/README.md

@@ -1,7 +1,6 @@
 # Pragma::Operation
 
 [![Build Status](https://travis-ci.org/pragmarb/pragma-operation.svg?branch=master)](https://travis-ci.org/pragmarb/pragma-operation)
-[![Dependency Status](https://gemnasium.com/badges/github.com/pragmarb/pragma-operation.svg)](https://gemnasium.com/github.com/pragmarb/pragma-operation)
 [![Coverage Status](https://coveralls.io/repos/github/pragmarb/pragma-operation/badge.svg?branch=master)](https://coveralls.io/github/pragmarb/pragma-operation?branch=master)
 [![Maintainability](https://api.codeclimate.com/v1/badges/e51e8d7489eb72ab97ba/maintainability)](https://codeclimate.com/github/pragmarb/pragma-operation/maintainability)
 

data/lib/pragma/operation.rb

@@ -19,6 +19,7 @@ require 'pragma/operation/response/no_content'
 require 'pragma/operation/response/unauthorized'
 require 'pragma/operation/response/service_unavailable'
 require 'pragma/operation/response/internal_server_error'
+require 'pragma/operation/response/conflict'
 require 'pragma/operation/response/payment_required'
 
 module Pragma

data/lib/pragma/operation/error.rb

@@ -2,15 +2,34 @@
 
 module Pragma
   module Operation
+    # A generic error entity to hold error information for HTTP responses.
+    #
+    # This format is not mandatory, but recommended for consistency and convenience.
     class Error
+      # @!attribute [r] error_type
+      #   @return [Symbol|String] a machine-readable error type
+      #
+      # @!attribute [r] error_message
+      #   @return [String] a human-readable error message
+      #
+      # @!attribute [r] meta
+      #   @return [Hash] metadata about the error
       attr_reader :error_type, :error_message, :meta
 
+      # Creates a new error entity.
+      #
+      # @param error_type [Symbol|String] a machine-readable error type
+      # @param error_message [String] a human-readable error message
+      # @param meta [Hash] metadata about the error
       def initialize(error_type:, error_message:, meta: {})
         @error_type = error_type
         @error_message = error_message
         @meta = meta
       end
 
+      # Converts the entity to a hash ready to be dumped as JSON.
+      #
+      # @return [Hash]
       def as_json(*)
         {
           error_type: error_type,
@@ -19,6 +38,11 @@ module Pragma
         }
       end
 
+      # Dumps the JSON representation as a JSON string.
+      #
+      # @return [String]
+      #
+      # @see #as_json
       def to_json
         JSON.dump as_json
       end

data/lib/pragma/operation/response.rb

@@ -2,6 +2,7 @@
 
 module Pragma
   module Operation
+    # Represents an HTTP response. Provides utilities to deal with status codes and such.
     class Response
       STATUSES = {
         100 => :continue,
@@ -64,23 +65,49 @@ module Pragma
         511 => :network_authentication_required
       }.freeze
 
+      # @!attribute [rw] entity
+      #   @return [Object] the entity/body of the response
+      #
+      # @!attribute [rw] headers
+      #   @return [Hash] the headers of the response
       attr_accessor :entity, :headers
+
+      # @!attribute [r] status
+      #   @return [Integer|Symbol] the HTTP status code of the response
       attr_reader :status
 
+      # Initializes the response.
+      #
+      # @param status [Integer|Symbol] the HTTP status code of the response
+      # @param entity [Object] the entity/body of the response
+      # @param headers [Hash] the headers of the response
       def initialize(status: 200, entity: nil, headers: {})
         self.status = status
         self.entity = entity
         self.headers = headers
       end
 
+      # Returns whether the response has a successful HTTP status code, by checking whether the
+      # status code is 1xx, 2xx or 3xx.
+      #
+      # @return [Boolean]
       def success?
         %w[1 2 3].include?(@status.to_s[0])
       end
 
+      # Returns whether the response has a failed HTTP status code, by checking whether the status
+      # code is 4xx or 5xx.
+      #
+      # @return [Boolean]
       def failure?
         !success?
       end
 
+      # Sets the HTTP status code of the response.
+      #
+      # @param v [Symbol|Integer] the status code (e.g. +200+/+:ok+)
+      #
+      # @raise [ArgumentError] if an invalid status code is provided
       def status=(v)
         case v
         when Integer
@@ -89,9 +116,19 @@ module Pragma
         when Symbol, String
           fail ArgumentError, "#{v} is not a valid status phrase" unless STATUSES.invert[v.to_sym]
           @status = STATUSES.invert[v.to_sym]
+        else
+          fail ArgumentError, "#status= expects an integer or a symbol, #{v} provided"
         end
       end
 
+      # Applies a decorator to the response's entity.
+      #
+      # @param decorator [Class] the decorator to apply
+      #
+      # @return [Response] returns itself for chaining
+      #
+      # @example Applying a decorator
+      #   response = Pragma::Operation::Response::Ok.new(entity: user).decorate_with(UserDecorator)
       def decorate_with(decorator)
         tap do
           self.entity = decorator.represent(entity)

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

@@ -3,6 +3,7 @@
 module Pragma
   module Operation
     class Response
+      # Represents the 400 Bad Request HTTP response.
       class BadRequest < Response
         def initialize(
           entity: Error.new(error_type: :bad_request, error_message: 'This request is malformed.'),

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Pragma
+  module Operation
+    class Response
+      # Represents the 409 Conflict HTTP response.
+      class Conflict < Response
+        def initialize(
+          entity: Error.new(
+            error_type: :conflict,
+            error_message: 'Your request is in conflict with other content on this server.'
+          ),
+          headers: {}
+        )
+          super(status: 409, entity: entity, headers: headers)
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,12 @@
 module Pragma
   module Operation
     class Response
+      # Represents the 201 Created HTTP response.
       class Created < Response
+        # Initializes the response.
+        #
+        # @param entity [Object] the response's entity
+        # @param headers [Hash] the response's headers
         def initialize(entity: nil, headers: {})
           super(status: 201, entity: entity, headers: headers)
         end

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

@@ -3,7 +3,12 @@
 module Pragma
   module Operation
     class Response
+      # Represents the 403 Forbidden HTTP response.
       class Forbidden < Response
+        # Initializes the response.
+        #
+        # @param entity [Object] the response's entity
+        # @param headers [Hash] the response's headers
         def initialize(
           entity: Error.new(
             error_type: :forbidden,

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

@@ -3,11 +3,16 @@
 module Pragma
   module Operation
     class Response
+      # Represents the 500 Internal Server Error HTTP response.
       class InternalServerError < Response
+        # Initializes the response.
+        #
+        # @param entity [Object] the response's entity
+        # @param headers [Hash] the response's headers
         def initialize(
           entity: Error.new(
             error_type: :internal_server_error,
-            error_message: 'There was an error processing your request.',
+            error_message: 'There was an error processing your request.'
           ),
           headers: {}
         )

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

@@ -3,7 +3,11 @@
 module Pragma
   module Operation
     class Response
+      # Represents the 204 No Content HTTP response.
       class NoContent < Response
+        # Initializes the response.
+        #
+        # @param headers [Hash] the response's headers
         def initialize(headers: {})
           super(status: 204, entity: nil, headers: headers)
         end

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

@@ -3,7 +3,12 @@
 module Pragma
   module Operation
     class Response
+      # Represents the 404 Not Found HTTP response.
       class NotFound < Response
+        # Initializes the response.
+        #
+        # @param entity [Object] the response's entity
+        # @param headers [Hash] the response's headers
         def initialize(
           entity: Error.new(
             error_type: :not_found,

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

@@ -3,7 +3,12 @@
 module Pragma
   module Operation
     class Response
+      # Represents the 200 Ok HTTP response.
       class Ok < Response
+        # Initializes the response.
+        #
+        # @param entity [Object] the response's entity
+        # @param headers [Hash] the response's headers
         def initialize(entity: nil, headers: {})
           super(status: 200, entity: entity, headers: headers)
         end

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

@@ -3,11 +3,16 @@
 module Pragma
   module Operation
     class Response
+      # Represents the 402 Payment Required HTTP response.
       class PaymentRequired < Response
+        # Initializes the response.
+        #
+        # @param entity [Object] the response's entity
+        # @param headers [Hash] the response's headers
         def initialize(
           entity: Error.new(
             error_type: :payment_required,
-            error_message: 'This resource requires payment.',
+            error_message: 'This resource requires payment.'
           ),
           headers: {}
         )

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

@@ -3,11 +3,16 @@
 module Pragma
   module Operation
     class Response
+      # Represents the 503 Service Unavailable HTTP response.
       class ServiceUnavailable < Response
+        # Initializes the response.
+        #
+        # @param entity [Object] the response's entity
+        # @param headers [Hash] the response's headers
         def initialize(
           entity: Error.new(
             error_type: :service_unavailable,
-            error_message: 'This resource is not available right now. Try later.',
+            error_message: 'This resource is not available right now. Try later.'
           ),
           headers: {}
         )

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

@@ -3,11 +3,16 @@
 module Pragma
   module Operation
     class Response
+      # Represents the 401 Unauthorized HTTP response.
       class Unauthorized < Response
+        # Initializes the response.
+        #
+        # @param entity [Object] the response's entity
+        # @param headers [Hash] the response's headers
         def initialize(
           entity: Error.new(
             error_type: :unauthorized,
-            error_message: 'This resource requires authentication.',
+            error_message: 'This resource requires authentication.'
           ),
           headers: {}
         )

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

@@ -3,7 +3,19 @@
 module Pragma
   module Operation
     class Response
+      # Represents the 422 Unprocessable Entity HTTP response.
       class UnprocessableEntity < Response
+        # Initializes the response.
+        #
+        # You can provide either +entity+ or +errors+, but not both. If you provide +entity+, the
+        # standard response's entity will be replaced with yours. If you provide +errors+, the
+        # standard entity will be used and your errors will be added to the meta.
+        #
+        # @param entity [Object] the response's entity
+        # @param headers [Hash] the response's headers
+        # @param errors [Hash] the response's errors
+        #
+        # @raise [ArgumentError] if both +entity+ and +errors+ are provided
         def initialize(entity: nil, headers: {}, errors: nil)
           fail ArgumentError, 'You cannot provide both :entity and :errors!' if entity && errors
 

data/lib/pragma/operation/version.rb

@@ -2,6 +2,6 @@
 
 module Pragma
   module Operation
-    VERSION = '2.1.0'
+    VERSION = '2.2.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pragma-operation
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Alessandro Desantis
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-02-14 00:00:00.000000000 Z
+date: 2018-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: trailblazer-operation
@@ -131,6 +131,7 @@ files:
 - lib/pragma/operation/error.rb
 - lib/pragma/operation/response.rb
 - lib/pragma/operation/response/bad_request.rb
+- lib/pragma/operation/response/conflict.rb
 - lib/pragma/operation/response/created.rb
 - lib/pragma/operation/response/forbidden.rb
 - lib/pragma/operation/response/internal_server_error.rb