Module: ActionController::Live

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

Overview

# Action Controller Live

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

Note that Rails includes ‘Rack::ETag` by default, which will buffer your response. As a result, streaming responses may not work properly with Rack 2.2.x, and you may need to implement workarounds in your application. You can either set the `ETag` or `Last-Modified` response headers or remove `Rack::ETag` from the middleware stack to address this issue.

Here’s an example of how you can set the ‘Last-Modified` header if your Rack version is 2.2.x:

def stream
  response.headers["Content-Type"] = "text/event-stream"
  response.headers["Last-Modified"] = Time.now.httpdate # Add this line if your Rack version is 2.2.x
  ...
end

## Streaming and Execution State

When streaming, the action is executed in a separate thread. By default, this thread shares execution state from the parent thread.

You can configure which execution state keys should be excluded from being shared using the ‘config.action_controller.live_streaming_excluded_keys` configuration:

# config/application.rb
config.action_controller.live_streaming_excluded_keys = [:active_record_connected_to_stack]

This is useful when using ActionController::Live inside a ‘connected_to` block. For example, if the parent request is reading from a replica using `connected_to(role: :reading)`, you may want the streaming thread to use its own connection context instead of inheriting the read-only context:

# Without configuration, streaming thread inherits read-only connection
ActiveRecord::Base.connected_to(role: :reading) do
  @posts = Post.all
  render stream: true # Streaming thread cannot write to database
end

# With configuration, streaming thread gets fresh connection context
# config.action_controller.live_streaming_excluded_keys = [:active_record_connected_to_stack]
ActiveRecord::Base.connected_to(role: :reading) do
  @posts = Post.all
  render stream: true # Streaming thread can write to database if needed
end

Common keys you might want to exclude:

  • ‘:active_record_connected_to_stack` - Database connection routing and roles

  • ‘:active_record_prohibit_shard_swapping` - Shard swapping restrictions

By default, no keys are excluded to maintain backward compatibility.

Defined Under Namespace

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

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.live_thread_pool_executor ⇒ Object 



417
418
419
 
# File 'lib/action_controller/metal/live.rb', line 417

def self.live_thread_pool_executor
  @live_thread_pool_executor ||= Concurrent::CachedThreadPool.new(name: "action_controller.live")
end

Instance Method Details

#original_clean_up_thread_locals ⇒ Object

Because of the above, we need to prevent the clearing of thread locals, since no new thread is actually spawned in the test environment.



34
 
# File 'lib/action_controller/test_case.rb', line 34

alias_method :original_clean_up_thread_locals, :clean_up_thread_locals

#original_new_controller_thread ⇒ Object

Disable controller / rendering threads in tests. User tests can access the database on the main thread, so they could open a txn, then the controller thread will open a new connection and try to access data that’s only visible to the main thread’s txn. This is the problem in #23483.



25
 
# File 'lib/action_controller/test_case.rb', line 25

alias_method :original_new_controller_thread, :new_controller_thread

#process(name) ⇒ Object 



307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
 
# File 'lib/action_controller/metal/live.rb', line 307

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 do
    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, except: self.class.live_streaming_excluded_keys) do
        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
        clean_up_thread_locals(locals, t2)

        @_response.commit!
      end
    end
  end

  @_response.await_commit

  raise error if error
end

#response_body=(body) ⇒ Object 



352
353
354
355
 
# File 'lib/action_controller/metal/live.rb', line 352

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



382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
 
# File 'lib/action_controller/metal/live.rb', line 382

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

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

    yield response.stream
  end
ensure
  response.stream.close
end