pragma-operation 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 3420ea754f34bea0b246202e61f6aec0df6d32a5c0ec7898d44c7deea6839a62
4
- data.tar.gz: 7791099085278d8dc3947222ab0cae339154b8ec56d3ce96512403031b18b37c
3
+ metadata.gz: 5d7f82fe38cc8a293b5ee3e99a22cf5fd700cdd24d5f2139c7e740414020fbb5
4
+ data.tar.gz: ca5b8bd2e1a558c1bb5874a4ed37b934fa8db6fda3e4b6346691e1a1fa857172
5
5
  SHA512:
6
- metadata.gz: 0bf7cdd63680130290bc38bdaea3b33c971a98bfcb06f8c059d0e5d686bc50733454f4cf68e8e1b91f1ba3e19f2dda61cf790bcaeb30473b8b57bb4cb34a02d6
7
- data.tar.gz: a3583c074377ed6739c27346a9746a6ac3cf389be390d348b0f91f2becf622b572c73a89d802ef74cbdade59edc61e50d4df0e0e8674b34af84d18de527f79f8
6
+ metadata.gz: 5976f017a997c16fdafc2051d82b5856d995403926f170ac9fdf004863f00dfb1164e718f461dab3d3607a295a9db451108f02a526b5df397322102709c060e4
7
+ data.tar.gz: f4b48e76ee2fb71e677ff1b110f94d8b37d2fe0f4c3e9dddecba2e535a1a32433fd2dec1ecfbc296f4dbcd265654e00a4fae2f832e76e94b1e6fa60ac07e7291
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.2.0]
11
+
12
+ ### Added
13
+
14
+ - Added `Conflict` response template
15
+
10
16
  ## [2.1.0]
11
17
 
12
18
  ### Added
@@ -24,6 +30,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
24
30
 
25
31
  First Pragma 2 release.
26
32
 
27
- [Unreleased]: https://github.com/pragmarb/pragma-operation/compare/v2.1.0...HEAD
33
+ [Unreleased]: https://github.com/pragmarb/pragma-operation/compare/v2.2.0...HEAD
34
+ [2.2.0]: https://github.com/pragmarb/pragma-operation/compare/v2.1.0...v2.2.0
28
35
  [2.1.0]: https://github.com/pragmarb/pragma-operation/compare/v2.0.0...v2.1.0
29
36
  [2.0.0]: https://github.com/pragmarb/pragma-operation/compare/v1.6.3...v2.0.0
data/README.md CHANGED
@@ -1,7 +1,6 @@
1
1
  # Pragma::Operation
2
2
 
3
3
  [![Build Status](https://travis-ci.org/pragmarb/pragma-operation.svg?branch=master)](https://travis-ci.org/pragmarb/pragma-operation)
4
- [![Dependency Status](https://gemnasium.com/badges/github.com/pragmarb/pragma-operation.svg)](https://gemnasium.com/github.com/pragmarb/pragma-operation)
5
4
  [![Coverage Status](https://coveralls.io/repos/github/pragmarb/pragma-operation/badge.svg?branch=master)](https://coveralls.io/github/pragmarb/pragma-operation?branch=master)
6
5
  [![Maintainability](https://api.codeclimate.com/v1/badges/e51e8d7489eb72ab97ba/maintainability)](https://codeclimate.com/github/pragmarb/pragma-operation/maintainability)
7
6
 
@@ -19,6 +19,7 @@ require 'pragma/operation/response/no_content'
19
19
  require 'pragma/operation/response/unauthorized'
20
20
  require 'pragma/operation/response/service_unavailable'
21
21
  require 'pragma/operation/response/internal_server_error'
22
+ require 'pragma/operation/response/conflict'
22
23
  require 'pragma/operation/response/payment_required'
23
24
 
24
25
  module Pragma
@@ -2,15 +2,34 @@
2
2
 
3
3
  module Pragma
4
4
  module Operation
5
+ # A generic error entity to hold error information for HTTP responses.
6
+ #
7
+ # This format is not mandatory, but recommended for consistency and convenience.
5
8
  class Error
9
+ # @!attribute [r] error_type
10
+ # @return [Symbol|String] a machine-readable error type
11
+ #
12
+ # @!attribute [r] error_message
13
+ # @return [String] a human-readable error message
14
+ #
15
+ # @!attribute [r] meta
16
+ # @return [Hash] metadata about the error
6
17
  attr_reader :error_type, :error_message, :meta
7
18
 
19
+ # Creates a new error entity.
20
+ #
21
+ # @param error_type [Symbol|String] a machine-readable error type
22
+ # @param error_message [String] a human-readable error message
23
+ # @param meta [Hash] metadata about the error
8
24
  def initialize(error_type:, error_message:, meta: {})
9
25
  @error_type = error_type
10
26
  @error_message = error_message
11
27
  @meta = meta
12
28
  end
13
29
 
30
+ # Converts the entity to a hash ready to be dumped as JSON.
31
+ #
32
+ # @return [Hash]
14
33
  def as_json(*)
15
34
  {
16
35
  error_type: error_type,
@@ -19,6 +38,11 @@ module Pragma
19
38
  }
20
39
  end
21
40
 
41
+ # Dumps the JSON representation as a JSON string.
42
+ #
43
+ # @return [String]
44
+ #
45
+ # @see #as_json
22
46
  def to_json
23
47
  JSON.dump as_json
24
48
  end
@@ -2,6 +2,7 @@
2
2
 
3
3
  module Pragma
4
4
  module Operation
5
+ # Represents an HTTP response. Provides utilities to deal with status codes and such.
5
6
  class Response
6
7
  STATUSES = {
7
8
  100 => :continue,
@@ -64,23 +65,49 @@ module Pragma
64
65
  511 => :network_authentication_required
65
66
  }.freeze
66
67
 
68
+ # @!attribute [rw] entity
69
+ # @return [Object] the entity/body of the response
70
+ #
71
+ # @!attribute [rw] headers
72
+ # @return [Hash] the headers of the response
67
73
  attr_accessor :entity, :headers
74
+
75
+ # @!attribute [r] status
76
+ # @return [Integer|Symbol] the HTTP status code of the response
68
77
  attr_reader :status
69
78
 
79
+ # Initializes the response.
80
+ #
81
+ # @param status [Integer|Symbol] the HTTP status code of the response
82
+ # @param entity [Object] the entity/body of the response
83
+ # @param headers [Hash] the headers of the response
70
84
  def initialize(status: 200, entity: nil, headers: {})
71
85
  self.status = status
72
86
  self.entity = entity
73
87
  self.headers = headers
74
88
  end
75
89
 
90
+ # Returns whether the response has a successful HTTP status code, by checking whether the
91
+ # status code is 1xx, 2xx or 3xx.
92
+ #
93
+ # @return [Boolean]
76
94
  def success?
77
95
  %w[1 2 3].include?(@status.to_s[0])
78
96
  end
79
97
 
98
+ # Returns whether the response has a failed HTTP status code, by checking whether the status
99
+ # code is 4xx or 5xx.
100
+ #
101
+ # @return [Boolean]
80
102
  def failure?
81
103
  !success?
82
104
  end
83
105
 
106
+ # Sets the HTTP status code of the response.
107
+ #
108
+ # @param v [Symbol|Integer] the status code (e.g. +200+/+:ok+)
109
+ #
110
+ # @raise [ArgumentError] if an invalid status code is provided
84
111
  def status=(v)
85
112
  case v
86
113
  when Integer
@@ -89,9 +116,19 @@ module Pragma
89
116
  when Symbol, String
90
117
  fail ArgumentError, "#{v} is not a valid status phrase" unless STATUSES.invert[v.to_sym]
91
118
  @status = STATUSES.invert[v.to_sym]
119
+ else
120
+ fail ArgumentError, "#status= expects an integer or a symbol, #{v} provided"
92
121
  end
93
122
  end
94
123
 
124
+ # Applies a decorator to the response's entity.
125
+ #
126
+ # @param decorator [Class] the decorator to apply
127
+ #
128
+ # @return [Response] returns itself for chaining
129
+ #
130
+ # @example Applying a decorator
131
+ # response = Pragma::Operation::Response::Ok.new(entity: user).decorate_with(UserDecorator)
95
132
  def decorate_with(decorator)
96
133
  tap do
97
134
  self.entity = decorator.represent(entity)
@@ -3,6 +3,7 @@
3
3
  module Pragma
4
4
  module Operation
5
5
  class Response
6
+ # Represents the 400 Bad Request HTTP response.
6
7
  class BadRequest < Response
7
8
  def initialize(
8
9
  entity: Error.new(error_type: :bad_request, error_message: 'This request is malformed.'),
@@ -0,0 +1,20 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Pragma
4
+ module Operation
5
+ class Response
6
+ # Represents the 409 Conflict HTTP response.
7
+ class Conflict < Response
8
+ def initialize(
9
+ entity: Error.new(
10
+ error_type: :conflict,
11
+ error_message: 'Your request is in conflict with other content on this server.'
12
+ ),
13
+ headers: {}
14
+ )
15
+ super(status: 409, entity: entity, headers: headers)
16
+ end
17
+ end
18
+ end
19
+ end
20
+ end
@@ -3,7 +3,12 @@
3
3
  module Pragma
4
4
  module Operation
5
5
  class Response
6
+ # Represents the 201 Created HTTP response.
6
7
  class Created < Response
8
+ # Initializes the response.
9
+ #
10
+ # @param entity [Object] the response's entity
11
+ # @param headers [Hash] the response's headers
7
12
  def initialize(entity: nil, headers: {})
8
13
  super(status: 201, entity: entity, headers: headers)
9
14
  end
@@ -3,7 +3,12 @@
3
3
  module Pragma
4
4
  module Operation
5
5
  class Response
6
+ # Represents the 403 Forbidden HTTP response.
6
7
  class Forbidden < Response
8
+ # Initializes the response.
9
+ #
10
+ # @param entity [Object] the response's entity
11
+ # @param headers [Hash] the response's headers
7
12
  def initialize(
8
13
  entity: Error.new(
9
14
  error_type: :forbidden,
@@ -3,11 +3,16 @@
3
3
  module Pragma
4
4
  module Operation
5
5
  class Response
6
+ # Represents the 500 Internal Server Error HTTP response.
6
7
  class InternalServerError < Response
8
+ # Initializes the response.
9
+ #
10
+ # @param entity [Object] the response's entity
11
+ # @param headers [Hash] the response's headers
7
12
  def initialize(
8
13
  entity: Error.new(
9
14
  error_type: :internal_server_error,
10
- error_message: 'There was an error processing your request.',
15
+ error_message: 'There was an error processing your request.'
11
16
  ),
12
17
  headers: {}
13
18
  )
@@ -3,7 +3,11 @@
3
3
  module Pragma
4
4
  module Operation
5
5
  class Response
6
+ # Represents the 204 No Content HTTP response.
6
7
  class NoContent < Response
8
+ # Initializes the response.
9
+ #
10
+ # @param headers [Hash] the response's headers
7
11
  def initialize(headers: {})
8
12
  super(status: 204, entity: nil, headers: headers)
9
13
  end
@@ -3,7 +3,12 @@
3
3
  module Pragma
4
4
  module Operation
5
5
  class Response
6
+ # Represents the 404 Not Found HTTP response.
6
7
  class NotFound < Response
8
+ # Initializes the response.
9
+ #
10
+ # @param entity [Object] the response's entity
11
+ # @param headers [Hash] the response's headers
7
12
  def initialize(
8
13
  entity: Error.new(
9
14
  error_type: :not_found,
@@ -3,7 +3,12 @@
3
3
  module Pragma
4
4
  module Operation
5
5
  class Response
6
+ # Represents the 200 Ok HTTP response.
6
7
  class Ok < Response
8
+ # Initializes the response.
9
+ #
10
+ # @param entity [Object] the response's entity
11
+ # @param headers [Hash] the response's headers
7
12
  def initialize(entity: nil, headers: {})
8
13
  super(status: 200, entity: entity, headers: headers)
9
14
  end
@@ -3,11 +3,16 @@
3
3
  module Pragma
4
4
  module Operation
5
5
  class Response
6
+ # Represents the 402 Payment Required HTTP response.
6
7
  class PaymentRequired < Response
8
+ # Initializes the response.
9
+ #
10
+ # @param entity [Object] the response's entity
11
+ # @param headers [Hash] the response's headers
7
12
  def initialize(
8
13
  entity: Error.new(
9
14
  error_type: :payment_required,
10
- error_message: 'This resource requires payment.',
15
+ error_message: 'This resource requires payment.'
11
16
  ),
12
17
  headers: {}
13
18
  )
@@ -3,11 +3,16 @@
3
3
  module Pragma
4
4
  module Operation
5
5
  class Response
6
+ # Represents the 503 Service Unavailable HTTP response.
6
7
  class ServiceUnavailable < Response
8
+ # Initializes the response.
9
+ #
10
+ # @param entity [Object] the response's entity
11
+ # @param headers [Hash] the response's headers
7
12
  def initialize(
8
13
  entity: Error.new(
9
14
  error_type: :service_unavailable,
10
- error_message: 'This resource is not available right now. Try later.',
15
+ error_message: 'This resource is not available right now. Try later.'
11
16
  ),
12
17
  headers: {}
13
18
  )
@@ -3,11 +3,16 @@
3
3
  module Pragma
4
4
  module Operation
5
5
  class Response
6
+ # Represents the 401 Unauthorized HTTP response.
6
7
  class Unauthorized < Response
8
+ # Initializes the response.
9
+ #
10
+ # @param entity [Object] the response's entity
11
+ # @param headers [Hash] the response's headers
7
12
  def initialize(
8
13
  entity: Error.new(
9
14
  error_type: :unauthorized,
10
- error_message: 'This resource requires authentication.',
15
+ error_message: 'This resource requires authentication.'
11
16
  ),
12
17
  headers: {}
13
18
  )
@@ -3,7 +3,19 @@
3
3
  module Pragma
4
4
  module Operation
5
5
  class Response
6
+ # Represents the 422 Unprocessable Entity HTTP response.
6
7
  class UnprocessableEntity < Response
8
+ # Initializes the response.
9
+ #
10
+ # You can provide either +entity+ or +errors+, but not both. If you provide +entity+, the
11
+ # standard response's entity will be replaced with yours. If you provide +errors+, the
12
+ # standard entity will be used and your errors will be added to the meta.
13
+ #
14
+ # @param entity [Object] the response's entity
15
+ # @param headers [Hash] the response's headers
16
+ # @param errors [Hash] the response's errors
17
+ #
18
+ # @raise [ArgumentError] if both +entity+ and +errors+ are provided
7
19
  def initialize(entity: nil, headers: {}, errors: nil)
8
20
  fail ArgumentError, 'You cannot provide both :entity and :errors!' if entity && errors
9
21
 
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Pragma
4
4
  module Operation
5
- VERSION = '2.1.0'
5
+ VERSION = '2.2.0'
6
6
  end
7
7
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: pragma-operation
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.1.0
4
+ version: 2.2.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Alessandro Desantis
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2018-02-14 00:00:00.000000000 Z
11
+ date: 2018-06-09 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: trailblazer-operation
@@ -131,6 +131,7 @@ files:
131
131
  - lib/pragma/operation/error.rb
132
132
  - lib/pragma/operation/response.rb
133
133
  - lib/pragma/operation/response/bad_request.rb
134
+ - lib/pragma/operation/response/conflict.rb
134
135
  - lib/pragma/operation/response/created.rb
135
136
  - lib/pragma/operation/response/forbidden.rb
136
137
  - lib/pragma/operation/response/internal_server_error.rb