Methods for sending arbitrary data and for streaming files to the browser, instead of rendering.

Methods
S
Constants
DEFAULT_SEND_FILE_OPTIONS = { :type => 'application/octet-stream'.freeze, :disposition => 'attachment'.freeze, :stream => true, :buffer_size => 4096, :x_sendfile => false }.freeze
 
X_SENDFILE_HEADER = 'X-Sendfile'.freeze
 
Instance Protected methods
send_data(data, options = {})

Sends the given binary data to the browser. This method is similar to render :text => data, but also allows you to specify whether the browser should display the response as a file attachment (i.e. in a download dialog) or as inline data. You may also set the content type, the apparent file name, and other things.

Options:

  • :filename- suggests a filename for the browser to use.

  • :type- specifies an HTTP content type. Defaults to 'application/octet-stream'. You can specify either a string or a symbol for a registered type register with Mime::Type.register, for example :json

  • :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'.

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_filefor more information on HTTP Content-* headers and caching.

Tip:if you want to stream large amounts of on-the-fly generated data to the browser, then use render :text => proc { ... } instead. See ActionController::Base#render for more information.

# File actionpack/lib/action_controller/streaming.rb, line 140
def send_data(data, options = {}) #:doc:
  logger.info "Sending data #{options[:filename]}" if logger
  send_file_headers! options.merge(:length => data.bytesize)
  @performed_render = false
  render :status => options[:status], :text => data
end
send_file(path, options = {})

Sends the file, by default streaming it 4096 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. You can optionally turn off streaming and send the whole file at once.

Be careful to sanitize the path parameter if it is 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'. You can specify either a string or a symbol for a registered type register with Mime::Type.register, for example :json

  • :length- used to manually override the length (in bytes) of the content that is going to be sent to the client. Defaults to File.size(path).

  • :disposition- specifies whether the file will be shown inline or downloaded. Valid values are 'inline' and 'attachment' (default).

  • :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 4096.

  • :status- specifies the status code to send with the response. Defaults to '200 OK'.

  • :url_based_filename- set to trueif you want the browser guess the filename from the URL, which is necessary for i18n filenames on certain browsers (setting :filenameoverrides this option).

  • :x_sendfile- uses X-Sendfile to send the file when set to true. This is currently only available with Lighttpd/Apache2 and specific modules installed and activated. Since this uses the web server to send the file, this may lower memory consumption on your server and it will not block your application for further requests. See blog.lighttpd.net/articles/2006/07/02/x-sendfile and tn123.ath.cx/mod_xsendfile/ for details. Defaults to false.

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) in 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.

# File actionpack/lib/action_controller/streaming.rb, line 79
def send_file(path, options = {}) #:doc:
  raise MissingFile, "Cannot read file #{path}" unless File.file?(path) and File.readable?(path)
  options[:length]   ||= File.size(path)
  options[:filename] ||= File.basename(path) unless options[:url_based_filename]
  send_file_headers! options
  @performed_render = false
  if options[:x_sendfile]
    logger.info "Sending #{X_SENDFILE_HEADER} header #{path}" if logger
    head options[:status], X_SENDFILE_HEADER => path
  else
    if options[:stream]
      render :status => options[:status], :text => Proc.new { |response, output|
        logger.info "Streaming file #{path}" unless logger.nil?
        len = options[:buffer_size] || 4096
        File.open(path, 'rb') do |file|
          while buf = file.read(len)
            output.write(buf)
          end
        end
      }
    else
      logger.info "Sending file #{path}" unless logger.nil?
      File.open(path, 'rb') { |file| render :status => options[:status], :text => file.read }
    end
  end
end