Module: Cyberweb::REST::Helpers

Included in:
Base
Defined in:
lib/cyberweb/REST/base/helpers/helpers.rb,
lib/cyberweb/REST/base/helpers/stream.rb

Overview

#

Methods available to routes, before/after filters, and views.

#

Defined Under Namespace

Classes: Stream

Constant Summary collapse

ETAG_KINDS =
#

ETAG_KINDS

#
i( strong weak )

Instance Method Summary collapse

Instance Method Details

#attachment(filename = nil, disposition = :attachment) ⇒ Object

#

attachment

Set the Content-Disposition to “attachment” with the specified filename, instructing the user agents to prompt to save.

#


352
353
354
355
356
357
358
359
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 352

def attachment(filename = nil, disposition = :attachment)
  response['Content-Disposition'] = disposition.to_s.dup
  return unless filename
  params = format('; filename="%s"', File.basename(filename))
  response['Content-Disposition'] << params
  ext = File.extname(filename)
  content_type(ext) unless response['Content-Type'] || ext.empty?
end

#back ⇒ Object

back

Sugar for redirect (example: redirect back)



257
258
259
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 257

def back
  request.referer
end

#bad_request? ⇒ Boolean

whether or not the status is set to 400

Returns:

  • (Boolean) 


294
295
296
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 294

def bad_request?
  status == 400
end

#body(value = nil, &block) ⇒ Object

#

body

Set or retrieve the response body. When a block is given, evaluation is deferred until the body is read with #each.

#


424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 424

def body(
    value = nil, &block
  )
  if block_given?
    def block.each; yield(call) end
    response.body = block
  elsif value
    # Rack 2.0 returns a Rack::File::Iterator here instead of
    # Rack::File as it was in the previous API.
    unless request.head? || value.is_a?(Rack::File::Iterator) || value.is_a?(Stream)
      headers.delete 'Content-Length'
    end
    response.body = value
  else
    response.body
  end
end

#cache_control(*values) ⇒ Object

#

cache_control

Specify response freshness policy for HTTP caches (Cache-Control header). Any number of non-value directives (:public, :private, :no_cache, :no_store, :must_revalidate, :proxy_revalidate) may be passed along with a Hash of value directives (:max_age, :s_maxage).

cache_control :public, :must_revalidate, :max_age => 60
=> Cache-Control: public, must-revalidate, max-age=60

See RFC 2616 / 14.9 for more on standard cache control directives:

https://tools.ietf.org/html/rfc2616#section-14.9.1
#


150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 150

def cache_control(*values)
  if values.last.is_a?(Hash)
    hash = values.pop
    hash.reject! { |_k, v| v == false }
    hash.reject! { |k, v| values << k if v == true }
  else
    hash = {}
  end

  values.map! { |value| value.to_s.tr('_', '-') }
  hash.each do |key, value|
    key = key.to_s.tr('_', '-')
    value = value.to_i if %w[max-age s-maxage].include? key
    values << "#{key}=#{value}"
  end

  response['Cache-Control'] = values.join(', ') if values.any?
end

#client_error? ⇒ Boolean

whether or not the status is set to 4xx

Returns:

  • (Boolean) 


279
280
281
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 279

def client_error?
  status.between? 400, 499
end

#content_type(type = nil, params = {}) ⇒ Object

#

content_type

Set the Content-Type of the response body given a media type or file extension.

#


324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 324

def content_type(type = nil, params = {})
  return response['Content-Type'] unless type

  default = params.delete :default
  mime_type = mime_type(type) || default
  raise format('Unknown media type: %p', type) if mime_type.nil?

  mime_type = mime_type.dup
  unless params.include?(:charset) || settings.add_charset.all? { |p| !(p === mime_type) }
    params[:charset] = params.delete('charset') || settings.default_encoding
  end
  params.delete :charset if mime_type.include? 'charset'
  unless params.empty?
    mime_type << (mime_type.include?(';') ? ', ' : ';')
    mime_type << params.map do |key, val|
      val = val.inspect if val =~ /[";,]/
      "#{key}=#{val}"
    end.join(', ')
  end
  response['Content-Type'] = mime_type
end

#error(code, body = nil) ⇒ Object

#

error

Halt processing and return the error status provided.

#


56
57
58
59
60
61
62
63
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 56

def error(code, body = nil)
  if code.respond_to? :to_str
    body = code.to_str
    code = 500
  end
  response.body = body unless body.nil?
  halt code
end

#etag(value, options = {}) ⇒ Object

etag

Set the response entity tag (HTTP ‘ETag’ header) and halt if conditional GET matches. The value argument is an identifier that uniquely identifies the current version of the resource. The kind argument indicates whether the etag should be used as a :strong (default) or :weak cache validator.

When the current request includes an ‘If-None-Match’ header with a matching etag, execution is immediately halted. If the request method is GET or HEAD, a ‘304 Not Modified’ response is sent.



227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 227

def etag(value, options = {})
  # Before touching this code, please double check RFC 2616 14.24 and 14.26.
  options      = { kind: options } unless Hash === options
  kind         = options[:kind] || :strong
  new_resource = options.fetch(:new_resource) { request.post? }

  unless ETAG_KINDS.include?(kind)
    raise ArgumentError, ':strong or :weak expected'
  end

  value = format('"%s"', value)
  value = "W/#{value}" if kind == :weak
  response['ETag'] = value

  return unless success? || status == 304

  if etag_matches?(env['HTTP_IF_NONE_MATCH'], new_resource)
    halt(request.safe? ? 304 : 412)
  end

  if env['HTTP_IF_MATCH']
    return if etag_matches?(env['HTTP_IF_MATCH'], new_resource)
    halt 412
  end
 nil
end

#expires(amount, *values) ⇒ Object

#

expires

Set the Expires header and Cache-Control/max-age directive. Amount can be an integer number of seconds in the future or a Time object indicating when the response should be considered “stale”.

The remaining “values” arguments are passed to the #cache_control helper:

expires 500, :public, :must_revalidate
=> Cache-Control: public, must-revalidate, max-age=500
=> Expires: Mon, 08 Jun 2009 08:50:17 GMT
#


117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 117

def expires(amount, *values)
  values << {} unless values.last.is_a?(Hash)

  if amount.is_a? Integer
    time    = Time.now + amount.to_i
    max_age = amount
  else
    time    = time_for amount
    max_age = time - Time.now
  end

  values.last.merge!(max_age: max_age) { |_key, v1, v2| v1 || v2 }
  cache_control(*values)

  response['Expires'] = time.httpdate
end

#headers(hash = nil) ⇒ Object

#

headers

Set multiple response headers with Hash.

#


70
71
72
73
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 70

def headers(hash = nil)
  response.headers.merge! hash if hash
  response.headers
end

#informational? ⇒ Boolean

informational?

whether or not the status is set to 1xx

Returns:

  • (Boolean) 


264
265
266
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 264

def informational?
  status.between? 100, 199
end

#last_modified(time) ⇒ Object

#

last_modified

Set the last modified time of the resource (HTTP ‘Last-Modified’ header) and halt if conditional GET matches. The time argument is a Time, DateTime, or other object that responds to to_time.

When the current request includes an ‘If-Modified-Since’ header that is equal or later than the time specified, execution is immediately halted with a ‘304 Not Modified’ response.

#


196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 196

def last_modified(time)
  return unless time
  time = time_for time
  response['Last-Modified'] = time.httpdate
  return if env['HTTP_IF_NONE_MATCH']

  if (status == 200) && env['HTTP_IF_MODIFIED_SINCE']
    # compare based on seconds since epoch
    since = Time.httpdate(env['HTTP_IF_MODIFIED_SINCE']).to_i
    halt 304 if since >= time.to_i
  end

  if (success? || (status == 412)) && env['HTTP_IF_UNMODIFIED_SINCE']
    # compare based on seconds since epoch
    since = Time.httpdate(env['HTTP_IF_UNMODIFIED_SINCE']).to_i
    halt 412 if since < time.to_i
  end
rescue ArgumentError
end

#logger ⇒ Object

#

logger

Access shared logger object.

#


89
90
91
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 89

def logger
  request.logger
end

#mime_type(type) ⇒ Object

#

mime_type

Look up a media type by file extension in Rack’s mime registry.

#


98
99
100
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 98

def mime_type(type)
  Base.mime_type(type)
end

#not_found(body = nil) ⇒ Object

#

not_found

Halt processing and return a 404 Not Found.

#


414
415
416
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 414

def not_found(body = nil)
  error 404, body
end

#not_found? ⇒ Boolean

whether or not the status is set to 404

Returns:

  • (Boolean) 


289
290
291
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 289

def not_found?
  status == 404
end

#redirect(uri, *args) ⇒ Object

#

redirect

Halt processing and redirect to the URI provided.

#


395
396
397
398
399
400
401
402
403
404
405
406
407
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 395

def redirect(uri, *args)
  if (env['HTTP_VERSION'] == 'HTTP/1.1') && (env['REQUEST_METHOD'] != 'GET')
    status 303
  else
    status 302
  end
  # ======================================================================= #
  # According to RFC 2616 section 14.30, "the field value consists of a
  # single absolute URI".
  # ======================================================================= #
  response['Location'] = uri(uri.to_s, settings.absolute_redirects?, settings.prefixed_redirects?)
  halt(*args)
end

#redirect? ⇒ Boolean

whether or not the status is set to 3xx

Returns:

  • (Boolean) 


274
275
276
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 274

def redirect?
  status.between? 300, 399
end

#send_file(path, opts = {}) ⇒ Object

#

send_file

Use the contents of the file at path as the response body.

#


366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 366

def send_file(path, opts = {})
  if opts[:type] || !response['Content-Type']
    content_type opts[:type] || File.extname(path), default: 'application/octet-stream'
  end

  disposition = opts[:disposition]
  filename    = opts[:filename]
  disposition = :attachment if disposition.nil? && filename
  filename    = path        if filename.nil?
  attachment(filename, disposition) if disposition

  last_modified opts[:last_modified] if opts[:last_modified]

  file   = Rack::File.new(File.dirname(settings.app_file))
  result = file.serving(request, path)

  result[1].each { |k, v| headers[k] ||= v }
  headers['Content-Length'] = result[1]['Content-Length']
  opts[:status] &&= Integer(opts[:status])
  halt (opts[:status] || result[0]), result[2]
rescue Errno::ENOENT
  not_found
end

#server_error? ⇒ Boolean

whether or not the status is set to 5xx

Returns:

  • (Boolean) 


284
285
286
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 284

def server_error?
  status.between? 500, 599
end

#session ⇒ Object

#

session

Access the underlying Rack session.

#


80
81
82
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 80

def session
  request.session
end

#status(value = nil) ⇒ Object

#

status

Set or retrieve the response status code.

#


447
448
449
450
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 447

def status(value = nil)
  response.status = Rack::Utils.status_code(value) if value
  response.status
end

#stream(keep_open = false) ⇒ Object

#

stream

Allows to start sending data to the client even though later parts of the response body have not yet been generated.

The close parameter specifies whether Stream#close should be called after the block has been executed. This is only relevant for evented servers like Rainbows.

#


179
180
181
182
183
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 179

def stream(keep_open = false)
  scheduler = env['async.callback'] ? EventMachine : Stream
  current   = @params.dup
  body Stream.new(scheduler, keep_open) { |out| with_params(current) { yield(out) } }
end

#success? ⇒ Boolean

whether or not the status is set to 2xx

Returns:

  • (Boolean) 


269
270
271
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 269

def success?
  status.between? 200, 299
end

#time_for(value) ⇒ Object

#

time_for

Generates a Time object from the given value. Used by #expires and #last_modified.

#


304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 304

def time_for(value)
  if value.is_a? Numeric
    Time.at value
  elsif value.respond_to? :to_s
    Time.parse value.to_s
  else
    value.to_time
  end
rescue ArgumentError => e
  raise e
rescue Exception
  raise ArgumentError, "unable to convert #{value.inspect} to a Time object"
end

#uri(addr = nil, absolute = true, add_script_name = true) ⇒ Object Also known as: url, to

#

uri

Generates the absolute URI for a given path in the app.

Takes Rack routers and reverse proxies into account.

#


30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/cyberweb/REST/base/helpers/helpers.rb', line 30

def uri(
    addr            = nil,
    absolute        = true,
    add_script_name = true
  )
  return addr if addr =~ /\A[a-z][a-z0-9+.\-]*:/i
  uri = [host = '']
  if absolute
    host << "http#{'s' if request.secure?}://"
    host << if request.forwarded? || (request.port != (request.secure? ? 443 : 80))
              request.host_with_port
            else
              request.host
            end
  end
  uri << request.script_name.to_s if add_script_name
  uri << (addr || request.path_info).to_s
  File.join(uri)
end