Module: ActionController::Live

Extended by:
ActiveSupport::Concern
Included in:
ActiveStorage::Streaming
Defined in:
actionpack/lib/action_controller/metal/live.rb,
actionpack/lib/action_controller/test_case.rb

Overview

Mix this module into your controller, and all actions in that controller will be able to stream data to the client as it's written.

class MyController < ActionController::Base
  include ActionController::Live

  def stream
    response.headers['Content-Type'] = 'text/event-stream'
    100.times {
      response.stream.write "hello world\n"
      sleep 1
    }
  ensure
    response.stream.close
  end
end

There are a few caveats with this module. You cannot write headers after the response has been committed (Response#committed? will return truthy). Calling write or close on the response stream will cause the response object to be committed. Make sure all headers are set before calling write or close on your stream.

You must call close on your stream when you're finished, otherwise the socket may be left open forever.

The final caveat is that your actions are executed in a separate thread than the main thread. Make sure your actions are thread safe, and this shouldn't be a problem (don't share state across threads, etc).

Defined Under Namespace

Modules: ClassMethods Classes: Buffer, ClientDisconnected, Response, SSE

Instance Method Summary collapse

Methods included from ActiveSupport::Concern

append_features, class_methods, extended, included, prepend_features, prepended

Instance Method Details

#process(name) ⇒ Object


249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
# File 'actionpack/lib/action_controller/metal/live.rb', line 249

def process(name)
  t1 = Thread.current
  locals = t1.keys.map { |key| [key, t1[key]] }

  error = nil
  # This processes the action in a child thread. It lets us return the
  # response code and headers back up the Rack stack, and still process
  # the body in parallel with sending data to the client.
  new_controller_thread {
    ActiveSupport::Dependencies.interlock.running do
      t2 = Thread.current

      # Since we're processing the view in a different thread, copy the
      # thread locals from the main thread to the child thread. :'(
      locals.each { |k, v| t2[k] = v }
      ActiveSupport::IsolatedExecutionState.share_with(t1)

      begin
        super(name)
      rescue => e
        if @_response.committed?
          begin
            @_response.stream.write(ActionView::Base.streaming_completion_on_exception) if request.format == :html
            @_response.stream.call_on_error
          rescue => exception
            log_error(exception)
          ensure
            log_error(e)
            @_response.stream.close
          end
        else
          error = e
        end
      ensure
        @_response.commit!
      end
    end
  }

  ActiveSupport::Dependencies.interlock.permit_concurrent_loads do
    @_response.await_commit
  end

  raise error if error
end

#response_body=(body) ⇒ Object


295
296
297
298
# File 'actionpack/lib/action_controller/metal/live.rb', line 295

def response_body=(body)
  super
  response.close if response
end

#send_stream(filename:, disposition: "attachment", type: nil) ⇒ Object

Sends a stream to the browser, which is helpful when you're generating exports or other running data where you don't want the entire file buffered in memory first. Similar to send_data, but where the data is generated live.

Options:

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

  • :type - specifies an HTTP content type. You can specify either a string or a symbol for a registered type with Mime::Type.register, for example :json. If omitted, type will be inferred from the file extension specified in :filename. If no content type is registered for the extension, the default type 'application/octet-stream' will be used.

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

Example of generating a csv export:

send_stream(filename: "subscribers.csv") do |stream|
  stream.write "email_address,updated_at\n"

  @subscribers.find_each do |subscriber|
    stream.write "#{subscriber.email_address},#{subscriber.updated_at}\n"
  end
end

321
322
323
324
325
326
327
328
329
330
331
332
333
# File 'actionpack/lib/action_controller/metal/live.rb', line 321

def send_stream(filename:, disposition: "attachment", type: nil)
  response.headers["Content-Type"] =
    (type.is_a?(Symbol) ? Mime[type].to_s : type) ||
    Mime::Type.lookup_by_extension(File.extname(filename).downcase.delete(".")) ||
    "application/octet-stream"

  response.headers["Content-Disposition"] =
    ActionDispatch::Http::ContentDisposition.format(disposition: disposition, filename: filename)

  yield response.stream
ensure
  response.stream.close
end