Module: Sinatra::Helpers

Included in:
Base
Defined in:
lib/sinatra/base.rb

Overview

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

Defined Under Namespace

Classes: Stream

Constant Summary collapse

MULTIPART_FORM_DATA_REPLACEMENT_TABLE =
{
  '"'  => '%22',
  "\r" => '%0D',
  "\n" => '%0A'
}.freeze
ETAG_KINDS =
%i[strong weak].freeze

Instance Method Summary collapse

Instance Method Details

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

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



414
415
416
417
418
419
420
421
422
# File 'lib/sinatra/base.rb', line 414

def attachment(filename = nil, disposition = :attachment)
  response['Content-Disposition'] = disposition.to_s.dup
  return unless filename

  params = format('; filename="%s"', File.basename(filename).gsub(/["\r\n]/, MULTIPART_FORM_DATA_REPLACEMENT_TABLE))
  response['Content-Disposition'] << params
  ext = File.extname(filename)
  content_type(ext) unless response['content-type'] || ext.empty?
end

#backObject

Sugar for redirect (example: redirect back)



650
651
652
# File 'lib/sinatra/base.rb', line 650

def back
  request.referer
end

#bad_request?Boolean

whether or not the status is set to 400

Returns:

  • (Boolean)


685
686
687
# File 'lib/sinatra/base.rb', line 685

def bad_request?
  status == 400
end

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

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



292
293
294
295
296
297
298
299
300
301
302
303
304
# File 'lib/sinatra/base.rb', line 292

def body(value = nil, &block)
  if block_given?
    def block.each; yield(call) end
    response.body = block
  elsif value
    unless request.head? || value.is_a?(Rack::Files::Iterator) || value.is_a?(Stream)
      headers.delete 'content-length'
    end
    response.body = value
  else
    response.body
  end
end

#cache_control(*values) ⇒ Object

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: http://tools.ietf.org/html/rfc2616#section-14.9.1



537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
# File 'lib/sinatra/base.rb', line 537

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)


670
671
672
# File 'lib/sinatra/base.rb', line 670

def client_error?
  status.between? 400, 499
end

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

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



383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
# File 'lib/sinatra/base.rb', line 383

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

Halt processing and return the error status provided.



346
347
348
349
350
351
352
353
# File 'lib/sinatra/base.rb', line 346

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

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.



620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
# File 'lib/sinatra/base.rb', line 620

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

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



565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
# File 'lib/sinatra/base.rb', line 565

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

Set multiple response headers with Hash.



361
362
363
364
# File 'lib/sinatra/base.rb', line 361

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

#informational?Boolean

whether or not the status is set to 1xx

Returns:

  • (Boolean)


655
656
657
# File 'lib/sinatra/base.rb', line 655

def informational?
  status.between? 100, 199
end

#last_modified(time) ⇒ Object

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.



589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
# File 'lib/sinatra/base.rb', line 589

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

#loggerObject

Access shared logger object.



372
373
374
# File 'lib/sinatra/base.rb', line 372

def logger
  request.logger
end

#mime_type(type) ⇒ Object

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



377
378
379
# File 'lib/sinatra/base.rb', line 377

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

#not_found(body = nil) ⇒ Object

Halt processing and return a 404 Not Found.



356
357
358
# File 'lib/sinatra/base.rb', line 356

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

#not_found?Boolean

whether or not the status is set to 404

Returns:

  • (Boolean)


680
681
682
# File 'lib/sinatra/base.rb', line 680

def not_found?
  status == 404
end

#redirect(uri, *args) ⇒ Object

Halt processing and redirect to the URI provided.



307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
# File 'lib/sinatra/base.rb', line 307

def redirect(uri, *args)
  # SERVER_PROTOCOL is required in Rack 3, fall back to HTTP_VERSION
  # for servers not updated for Rack 3 (like Puma 5)
  http_version = env['SERVER_PROTOCOL'] || env['HTTP_VERSION']
  if (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)


665
666
667
# File 'lib/sinatra/base.rb', line 665

def redirect?
  status.between? 300, 399
end

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

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



425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
# File 'lib/sinatra/base.rb', line 425

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::Files.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)


675
676
677
# File 'lib/sinatra/base.rb', line 675

def server_error?
  status.between? 500, 599
end

#sessionObject

Access the underlying Rack session.



367
368
369
# File 'lib/sinatra/base.rb', line 367

def session
  request.session
end

#status(value = nil) ⇒ Object

Set or retrieve the response status code.



285
286
287
288
# File 'lib/sinatra/base.rb', line 285

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

#stream(keep_open = false) ⇒ Object

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.



512
513
514
515
516
517
518
519
520
521
522
523
524
525
# File 'lib/sinatra/base.rb', line 512

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

#success?Boolean

whether or not the status is set to 2xx

Returns:

  • (Boolean)


660
661
662
# File 'lib/sinatra/base.rb', line 660

def success?
  status.between? 200, 299
end

#time_for(value) ⇒ Object

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



691
692
693
694
695
696
697
698
699
700
701
702
703
# File 'lib/sinatra/base.rb', line 691

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

Generates the absolute URI for a given path in the app. Takes Rack routers and reverse proxies into account.



325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
# File 'lib/sinatra/base.rb', line 325

def uri(addr = nil, absolute = true, add_script_name = true)
  return addr if addr.to_s =~ /\A[a-z][a-z0-9+.\-]*:/i

  uri = [host = String.new]
  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