Module: ActionController::Live
Relationships & Source Files | |
Namespace Children | |
Modules:
| |
Classes:
| |
Exceptions:
| |
Super Chains via Extension / Inclusion / Inheritance | |
Class Chain:
self,
::ActiveSupport::Concern
|
|
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).
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
Class Method Summary
- .live_thread_pool_executor private
::ActiveSupport::Concern
- Extended
class_methods | Define class methods from given block. |
included | Evaluate given block in context of base class, so that you can write class macros here. |
prepended | Evaluate given block in context of base class, so that you can write class macros here. |
append_features, prepend_features |
Instance Attribute Summary
- #response_body=(body) writeonly
Instance Method Summary
-
#original_new_controller_thread
Disable controller / rendering threads in tests.
- #process(name)
-
#send_stream(filename:, disposition: "attachment", type: nil)
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.
- #log_error(exception) private
-
#new_controller_thread
private
Internal use only
Spawn a new thread to serve up the controller in.
Class Method Details
.live_thread_pool_executor (private)
[ GitHub ]# File 'actionpack/lib/action_controller/metal/live.rb', line 385
def self.live_thread_pool_executor @live_thread_pool_executor ||= Concurrent::CachedThreadPool.new(name: "action_controller.live") end
Instance Attribute Details
#response_body=(body) (writeonly)
[ GitHub ]# File 'actionpack/lib/action_controller/metal/live.rb', line 326
def response_body=(body) super response.close if response end
Instance Method Details
#log_error(exception) (private)
[ GitHub ]# File 'actionpack/lib/action_controller/metal/live.rb', line 389
def log_error(exception) logger = ActionController::Base.logger return unless logger logger.fatal do = +"\n#{exception.class} (#{exception.}):\n" << exception.annotated_source_code.to_s if exception.respond_to?(:annotated_source_code) << " " << exception.backtrace.join("\n ") "#{}\n\n" end end
#new_controller_thread (private)
Spawn a new thread to serve up the controller in. This is to get around the fact that ::Rack
isn’t based around IOs and we need to use a thread to stream data from the response bodies. Nobody should call this method except in ::Rails
internals. Seriously!
See additional method definition at file actionpack/lib/action_controller/test_case.rb line 28.
# File 'actionpack/lib/action_controller/metal/live.rb', line 377
def new_controller_thread # :nodoc: yield end
#original_new_controller_thread
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.
# File 'actionpack/lib/action_controller/test_case.rb', line 25
alias_method :original_new_controller_thread, :new_controller_thread
#process(name)
[ GitHub ]# File 'actionpack/lib/action_controller/metal/live.rb', line 276
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 # Ensure we clean up any thread locals we copied so that the thread can reused. ActiveSupport::IsolatedExecutionState.clear locals.each { |k, _| t2[k] = nil } @_response.commit! end end } ActiveSupport::Dependencies.interlock.permit_concurrent_loads do @_response.await_commit end raise error if error end
#send_stream(filename:, disposition: "attachment", type: nil)
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
# File 'actionpack/lib/action_controller/metal/live.rb', line 355
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