Module Sinatra::Streaming

  1. lib/sinatra.rb

Methods for sending files and streams to the browser instead of rendering.

Methods

protected instance

  1. send_data
  2. send_file

Constants

DEFAULT_SEND_FILE_OPTIONS = { :type => 'application/octet-stream'.freeze, :disposition => 'attachment'.freeze, :stream => true, :buffer_size => 8192 }.freeze

Protected instance methods

send_data (data, options = {})

Send binary data to the user as a file download. May set content type, apparent file name, and specify whether to show data inline or download as an attachment.

Options:

  • :filename - Suggests a filename for the browser to use.
  • :type - specifies an HTTP content type. Defaults to ‘application/octet-stream’.
  • :disposition - specifies whether the file will be shown inline or downloaded. Valid values are ‘inline’ and ‘attachment’ (default).
  • :status - specifies the status code to send with the response. Defaults to ‘200 OK’.
  • :last_modified - an optional RFC 2616 formatted date value (See Time#httpdate) indicating the last modified time of the response entity. If the request includes an If-Modified-Since header that matches this value exactly, a 304 Not Modified response is sent instead of the data.

Generic data download:

send_data buffer

Download a dynamically-generated tarball:

send_data generate_tgz('dir'), :filename => 'dir.tgz'

Display an image Active Record in the browser:

send_data image.data,
  :type => image.content_type,
  :disposition => 'inline'

See send_file for more information on HTTP Content-* headers and caching.

[show source]
     # File lib/sinatra.rb, line 355
355:     def send_data(data, options = {}) #:doc:
356:       send_file_headers! options.merge(:length => data.size)
357:       throw :halt, [options[:status] || 200, [data]]
358:     end
send_file (path, options = {})

Sends the file by streaming it 8192 bytes at a time. This way the whole file doesn’t need to be read into memory at once. This makes it feasible to send even large files.

Be careful to sanitize the path parameter if it coming from a web page. send_file(params[:path]) allows a malicious user to download any file on your server.

Options:

  • :filename - suggests a filename for the browser to use. Defaults to File.basename(path).
  • :type - specifies an HTTP content type. Defaults to ‘application/octet-stream’.
  • :disposition - specifies whether the file will be shown inline or downloaded. Valid values are ‘inline’ and ‘attachment’ (default). When set to nil, the Content-Disposition and Content-Transfer-Encoding headers are omitted entirely.
  • :stream - whether to send the file to the user agent as it is read (true) or to read the entire file before sending (false). Defaults to true.
  • :buffer_size - specifies size (in bytes) of the buffer used to stream the file. Defaults to 8192.
  • :status - specifies the status code to send with the response. Defaults to ‘200 OK’.
  • :last_modified - an optional RFC 2616 formatted date value (See Time#httpdate) indicating the last modified time of the file. If the request includes an If-Modified-Since header that matches this value exactly, a 304 Not Modified response is sent instead of the file. Defaults to the file’s last modified time.

The default Content-Type and Content-Disposition headers are set to download arbitrary binary files in as many browsers as possible. IE versions 4, 5, 5.5, and 6 are all known to have a variety of quirks (especially when downloading over SSL).

Simple download:

send_file '/path/to.zip'

Show a JPEG in the browser:

send_file '/path/to.jpeg',
  :type => 'image/jpeg',
  :disposition => 'inline'

Show a 404 page in the browser:

send_file '/path/to/404.html,
  :type => 'text/html; charset=utf-8',
  :status => 404

Read about the other Content-* HTTP headers if you’d like to provide the user with more information (such as Content-Description). www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11

Also be aware that the document may be cached by proxies and browsers. The Pragma and Cache-Control headers declare how the file may be cached by intermediaries. They default to require clients to validate with the server before releasing cached responses. See www.mnot.net/cache_docs/ for an overview of web caching and www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9 for the Cache-Control header spec.

[show source]
     # File lib/sinatra.rb, line 308
308:     def send_file(path, options = {}) #:doc:
309:       raise MissingFile, "Cannot read file #{path}" unless File.file?(path) and File.readable?(path)
310: 
311:       options[:length]   ||= File.size(path)
312:       options[:filename] ||= File.basename(path)
313:       options[:type] ||= Rack::File::MIME_TYPES[File.extname(options[:filename])[1..-1]] || 'text/plain'
314:       options[:last_modified] ||= File.mtime(path).httpdate
315:       options[:stream] = true unless options.key?(:stream)
316:       options[:buffer_size] ||= DEFAULT_SEND_FILE_OPTIONS[:buffer_size]
317:       send_file_headers! options
318: 
319:       if options[:stream]
320:         throw :halt, [options[:status] || 200, FileStreamer.new(path, options)]
321:       else
322:         File.open(path, 'rb') { |file| throw :halt, [options[:status] || 200, [file.read]] }
323:       end
324:     end