Class: Praxis::ResponseDefinition

Inherits:
Object
  • Object
show all
Defined in:
lib/praxis/response_definition.rb

Overview

Response spec DSL container

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(response_name, **spec, &block) ⇒ ResponseDefinition

Returns a new instance of ResponseDefinition.



8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
# File 'lib/praxis/response_definition.rb', line 8

def initialize(response_name, **spec, &block)
  unless response_name
    raise Exceptions::InvalidConfiguration.new(
      "Response name is required for a response specification"
    )
  end
  @spec = { headers:{} }
  @name = response_name
  self.instance_exec(**spec, &block) if block_given?

  if self.status.nil?
    raise Exceptions::InvalidConfiguration.new(
      "Status code is required for a response specification"
    )
  end
end

Instance Attribute Details

#name ⇒ Object (readonly)

Returns the value of attribute name.



6
7
8
 
# File 'lib/praxis/response_definition.rb', line 6

def name
  @name
end

Instance Method Details

#_describe_header(data) ⇒ Object 



175
176
177
178
179
 
# File 'lib/praxis/response_definition.rb', line 175

def _describe_header(data)
  data_type = data.is_a?(Regexp) ? :regexp : :string
  data_value = data.is_a?(Regexp) ? data.inspect : data
  { :value => data_value, :type => data_type }
end

#describe(context: nil) ⇒ Object 



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/praxis/response_definition.rb', line 118

def describe(context: nil)
  location_type = location.is_a?(Regexp) ? :regexp : :string
  location_value = location.is_a?(Regexp) ? location.inspect : location
  content = {
    :description => description,
    :status => status,
    :headers => {}
  }
  content[:location] = _describe_header(location) unless location == nil

  unless headers == nil
    headers.each do |name, value|
      content[:headers][name] = _describe_header(value)
    end
  end

  if self.media_type
    payload = media_type.describe(true)

    if (example_payload = self.example(context))
      payload[:examples] = {}
      rendered_payload = example_payload.dump

      # FIXME: remove load when when MediaTypeCommon.identifier returns a MediaTypeIdentifier
      identifier = MediaTypeIdentifier.load(self.media_type.identifier)

      default_handlers = ApiDefinition.instance.info.produces

      handlers = Praxis::Application.instance.handlers.select do |k,v|
        default_handlers.include?(k)
      end

      if (identifier && handler = handlers[identifier.handler_name])
        payload[:examples][identifier.handler_name] = {
          content_type: identifier.to_s,
          body: handler.generate(rendered_payload)
        }
      else
        handlers.each do |name, handler|
          content_type = ( identifier ) ? identifier + name : 'application/' + name
          payload[:examples][name] = {
            content_type: content_type.to_s,
            body: handler.generate(rendered_payload)
          }
        end
      end
    end

    content[:payload] = payload
  end

  unless parts == nil
    content[:parts_like] = parts.describe
  end
  content
end

#description(text = nil) ⇒ Object 



25
26
27
28
 
# File 'lib/praxis/response_definition.rb', line 25

def description(text=nil)
  return @spec[:description] if text.nil?
  @spec[:description] = text
end

#example(context = nil) ⇒ Object 



106
107
108
109
110
111
112
113
114
115
 
# File 'lib/praxis/response_definition.rb', line 106

def example(context=nil)
  return nil if self.media_type.nil?
  return nil if self.media_type.kind_of?(SimpleMediaType)

  if context.nil?
    context = "#{self.media_type.name}-#{self.name}"
  end

  self.media_type.example(context)
end

#header(hdr) ⇒ Object 



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/praxis/response_definition.rb', line 85

def header(hdr)
  case hdr
  when String
    @spec[:headers][hdr] = true
  when Hash
    hdr.each do | k, v |
      unless v.is_a?(Regexp) || v.is_a?(String)
        raise Exceptions::InvalidConfiguration.new(
          "Header definitions for #{k.inspect} can only match values of type String or Regexp. Received: #{v.inspect}"
        )
      end
      @spec[:headers][k] = v
    end
  else
    raise Exceptions::InvalidConfiguration.new(
      "A header definition can only take a String (to match the name) or" +
      " a Hash (to match both the name and the value). Received: #{hdr.inspect}"
    )
  end
end

#headers(hdrs = nil) ⇒ Object 



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/praxis/response_definition.rb', line 68

def headers(hdrs = nil)
  return @spec[:headers] if hdrs.nil?

  case hdrs
  when Array
    hdrs.each {|header_name| header(header_name) }
  when Hash
    header(hdrs)
  when String
    header(hdrs)
  else
    raise Exceptions::InvalidConfiguration.new(
      "Invalid headers specification: Arrays, Hash, or String must be used. Received: #{hdrs.inspect}"
    )
  end
end

#location(loc = nil) ⇒ Object 



58
59
60
61
62
63
64
65
66
 
# File 'lib/praxis/response_definition.rb', line 58

def location(loc=nil)
  return @spec[:location] if loc.nil?
  unless ( loc.is_a?(Regexp) || loc.is_a?(String) )
    raise Exceptions::InvalidConfiguration.new(
      "Invalid location specification. Location in response must be either a regular expression or a string."
    )
  end
  @spec[:location] = loc
end

#media_type(media_type = nil) ⇒ Object 



35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/praxis/response_definition.rb', line 35

def media_type(media_type=nil)
  return @spec[:media_type] if media_type.nil?

  @spec[:media_type] = case media_type
  when String
    SimpleMediaType.new(media_type)
  when Class
    if media_type < Praxis::Types::MediaTypeCommon
      media_type
    else
      raise Exceptions::InvalidConfiguration.new(
        'Invalid media_type specification. media_type must be a Praxis::MediaType'
      )
    end
  when SimpleMediaType
    media_type
  else
    raise Exceptions::InvalidConfiguration.new(
      'Invalid media_type specification. media_type must be a String, MediaType or SimpleMediaType'
    )
  end
end

#parts(proc = nil, like: nil, **args, &block) ⇒ Object 



193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/praxis/response_definition.rb', line 193

def parts(proc=nil, like: nil,  **args, &block)
  a_proc = proc || block
  if like.nil? && !a_proc
    raise ArgumentError, "Parts definition for response #{name} needs a :like argument or a block/proc" if !args.empty?
    return @parts
  end
  if like && a_proc
    raise ArgumentError, "Parts definition for response #{name} does not allow :like and a block simultaneously"
  end
  if like
    template = ApiDefinition.instance.response(like)
    @parts = template.compile(nil, **args)
  else # block
    @parts = Praxis::ResponseDefinition.new('anonymous', **args, &a_proc)
  end
end

#status(code = nil) ⇒ Object 



30
31
32
33
 
# File 'lib/praxis/response_definition.rb', line 30

def status(code=nil)
  return @spec[:status] if code.nil?
  @spec[:status] = code
end

#validate(response, validate_body: false) ⇒ Object 



181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/praxis/response_definition.rb', line 181

def validate(response, validate_body: false)
  validate_status!(response)
  validate_location!(response)
  validate_headers!(response)
  validate_content_type!(response)
  validate_parts!(response)

  if validate_body
    validate_body!(response)
  end
end

#validate_body!(response) ⇒ Object

Validates response body

Parameters:

  • response (Object)

Raises:



298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/praxis/response_definition.rb', line 298

def validate_body!(response)
  return unless media_type
  return if media_type.kind_of? SimpleMediaType

  errors = self.media_type.validate(self.media_type.load(response.body))
  if errors.any?
    message = "Invalid response body for #{media_type.identifier}." +
      "Errors: #{errors.inspect}"
      raise Exceptions::Validation.new(message, errors: errors)
  end

end

#validate_content_type!(response) ⇒ Object

Validates Content-Type header and response media type

Parameters:

  • response (Object)

Raises:



279
280
281
282
283
284
285
286
287
288
289
290
291
 
# File 'lib/praxis/response_definition.rb', line 279

def validate_content_type!(response)
  return unless media_type

  response_content_type = response.content_type
  expected_content_type = Praxis::MediaTypeIdentifier.load(media_type.identifier)

  unless expected_content_type.match(response_content_type)
    raise Exceptions::Validation.new(
      "Bad Content-Type header. #{response_content_type}" +
      " is incompatible with #{expected_content_type} as described in response: #{self.name}"
    )
  end
end

#validate_headers!(response) ⇒ Object

Validates Headers

Raises:



240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/praxis/response_definition.rb', line 240

def validate_headers!(response)
  return unless headers
  headers.each do |name, value|
    if name.is_a? Symbol
      raise Exceptions::Validation.new(
        "Symbols are not supported in headers"
      )
    end

    unless response.headers.has_key?(name)
      raise Exceptions::Validation.new(
        "Header #{name.inspect} was required but is missing"
      )
    end

    case value
    when String
      if response.headers[name] != value
        raise Exceptions::Validation.new(
          "Header #{name.inspect}, with value #{value.inspect} does not match #{response.headers[name]}."
        )
      end
    when Regexp
      if response.headers[name] !~ value
        raise Exceptions::Validation.new(
          "Header #{name.inspect}, with value #{value.inspect} does not match #{response.headers[name].inspect}."
        )
      end
    end
  end
end

#validate_location!(response) ⇒ Object

Validates ‘Location’ header

Raises:



230
231
232
233
 
# File 'lib/praxis/response_definition.rb', line 230

def validate_location!(response)
  return if location.nil? || location === response.headers['Location']
  raise Exceptions::Validation.new("LOCATION does not match #{location.inspect}")
end

#validate_parts!(response) ⇒ Object 



311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
 
# File 'lib/praxis/response_definition.rb', line 311

def validate_parts!(response)
  return unless parts

  case response.body
  when Praxis::Types::MultipartArray
    response.body.each do |part|
      parts.validate(part)
    end
  else
    # TODO: remove with other Multipart deprecations.
    response.parts.each do |name, part|
      parts.validate(part)
    end
  end
end

#validate_status!(response) ⇒ Object

Validates Status code

Raises:



214
215
216
217
218
219
220
221
222
223
 
# File 'lib/praxis/response_definition.rb', line 214

def validate_status!(response)
  return unless status
  # Validate status code if defined in the spec
  if response.status != status
    raise Exceptions::Validation.new(
      "Invalid response code detected. Response %s dictates status of %s but this response is returning %s." %
      [name, status.inspect, response.status.inspect]
    )
  end
end