Several fixes for AC::Streaming

zzak · zzak · commit 766564f78f27 · 2023-01-29T08:35:33.000+09:00
diff --git a/actionpack/lib/action_controller/metal/streaming.rb b/actionpack/lib/action_controller/metal/streaming.rb
@@ -9,22 +9,17 @@ module ActionController # :nodoc:
   # and then the layout. The response is sent to the client after the whole
   # template is rendered, all queries are made, and the layout is processed.
   #
-  # Streaming inverts the rendering flow by rendering the layout first and
-  # streaming each part of the layout as they are processed. This allows the
+  # \Streaming inverts the rendering flow by rendering the layout first and
+  # subsequently each part of the layout as they are processed. This allows the
   # header of the HTML (which is usually in the layout) to be streamed back
-  # to client very quickly, allowing JavaScripts and stylesheets to be loaded
+  # to client very quickly, enabling JavaScripts and stylesheets to be loaded
   # earlier than usual.
   #
-  # This approach was introduced in Rails 3.1 and is still improving. Several
-  # Rack middlewares may not work and you need to be careful when streaming.
-  # Those points are going to be addressed soon.
+  # Several Rack middlewares may not work and you need to be careful when streaming.
+  # This is covered in more detail below, see the "Middlewares" section.
   #
-  # In order to use streaming, you will need to use a Ruby version that
-  # supports fibers (fibers are supported since version 1.9.2 of the main
-  # Ruby implementation).
-  #
-  # Streaming can be added to a given template easily, all you need to do is
-  # to pass the +:stream+ option.
+  # \Streaming can be added to a given template easily, all you need to do is
+  # to pass the +:stream+ option to +render+.
   #
   #   class PostsController
   #     def index
@@ -35,7 +30,7 @@ module ActionController # :nodoc:
   #
   # == When to use streaming
   #
-  # Streaming may be considered to be overkill for lightweight actions like
+  # \Streaming may be considered to be overkill for lightweight actions like
   # +new+ or +edit+. The real benefit of streaming is on expensive actions
   # that, for example, do a lot of queries on the database.
   #
@@ -59,7 +54,7 @@ module ActionController # :nodoc:
   #     render stream: true
   #   end
   #
-  # Notice that +:stream+ only works with templates. Rendering +:json+
+  # Notice that +:stream+ only works with templates. \Rendering +:json+
   # or +:xml+ with +:stream+ won't work.
   #
   # == Communication between layout and template
@@ -112,7 +107,7 @@ module ActionController # :nodoc:
   # This means that, if you have <code>yield :title</code> in your layout
   # and you want to use streaming, you would have to render the whole template
   # (and eventually trigger all queries) before streaming the title and all
-  # assets, which kills the purpose of streaming. For this purpose, you can use
+  # assets, which defeats the purpose of streaming. Alternatively, you can use
   # a helper called +provide+ that does the same as +content_for+ but tells the
   # layout to stop searching for other entries and continue rendering.
   #
@@ -122,7 +117,7 @@ module ActionController # :nodoc:
   #   Hello
   #   <%= content_for :title, " page" %>
   #
-  # Giving:
+  # Resulting in:
   #
   #   <html>
   #     <head><title>Main</title></head>
@@ -132,6 +127,8 @@ module ActionController # :nodoc:
   # That said, when streaming, you need to properly check your templates
   # and choose when to use +provide+ and +content_for+.
   #
+  # See also ActionView::Helpers::CaptureHelper for more information.
+  #
   # == Headers, cookies, session, and flash
   #
   # When streaming, the HTTP headers are sent to the client right before
@@ -161,9 +158,9 @@ module ActionController # :nodoc:
   #
   #   "><script>window.location = "/500.html"</script></html>
   #
-  # The first two characters (">) are required in case the exception happens
-  # while rendering attributes for a given tag. You can check the real cause
-  # for the exception in your logger.
+  # The first two characters (<tt>"></tt>) are required in case the exception
+  # happens while rendering attributes for a given tag. You can check the real
+  # cause for the exception in your logger.
   #
   # == Web server support
   #
@@ -183,11 +180,13 @@ module ActionController # :nodoc:
   #   unicorn_rails --config-file unicorn.config.rb
   #
   # You may also want to configure other parameters like <tt>:tcp_nodelay</tt>.
+  #
   # Please check its documentation for more information:
-  # https://bogomips.org/unicorn/Unicorn/Configurator.html#method-i-listen
+  #
+  # * https://bogomips.org/unicorn/Unicorn/Configurator.html#method-i-listen
   #
   # If you are using Unicorn with NGINX, you may need to tweak NGINX.
-  # Streaming should work out of the box on Rainbows.
+  # \Streaming should work out of the box on Rainbows.
   #
   # ==== Passenger
   #
@@ -203,7 +202,8 @@ module ActionController # :nodoc:
   # the response back to the client.
   #
   # Please check the documentation for more information:
-  # https://www.phusionpassenger.com/docs/references/config_reference/nginx/#passenger_buffer_response
+  #
+  # * https://www.phusionpassenger.com/docs/references/config_reference/nginx/#passenger_buffer_response
   #
   module Streaming
     private

Original file line number	Diff line number	Diff line change
`@@ -9,22 +9,17 @@ module ActionController # :nodoc:`
`9`	`9`	`# and then the layout. The response is sent to the client after the whole`
`10`	`10`	`# template is rendered, all queries are made, and the layout is processed.`
`11`	`11`	`#`
`12`		`- # Streaming inverts the rendering flow by rendering the layout first and`
`13`		`- # streaming each part of the layout as they are processed. This allows the`
	`12`	`+ # \Streaming inverts the rendering flow by rendering the layout first and`
	`13`	`+ # subsequently each part of the layout as they are processed. This allows the`
`14`	`14`	`# header of the HTML (which is usually in the layout) to be streamed back`
`15`		`- # to client very quickly, allowing JavaScripts and stylesheets to be loaded`
	`15`	`+ # to client very quickly, enabling JavaScripts and stylesheets to be loaded`
`16`	`16`	`# earlier than usual.`
`17`	`17`	`#`
`18`		`- # This approach was introduced in Rails 3.1 and is still improving. Several`
`19`		`- # Rack middlewares may not work and you need to be careful when streaming.`
`20`		`- # Those points are going to be addressed soon.`
	`18`	`+ # Several Rack middlewares may not work and you need to be careful when streaming.`
	`19`	`+ # This is covered in more detail below, see the "Middlewares" section.`
`21`	`20`	`#`
`22`		`- # In order to use streaming, you will need to use a Ruby version that`
`23`		`- # supports fibers (fibers are supported since version 1.9.2 of the main`
`24`		`- # Ruby implementation).`
`25`		`- #`
`26`		`- # Streaming can be added to a given template easily, all you need to do is`
`27`		`- # to pass the +:stream+ option.`
	`21`	`+ # \Streaming can be added to a given template easily, all you need to do is`
	`22`	`+ # to pass the +:stream+ option to +render+.`
`28`	`23`	`#`
`29`	`24`	`# class PostsController`
`30`	`25`	`# def index`
`@@ -35,7 +30,7 @@ module ActionController # :nodoc:`
`35`	`30`	`#`
`36`	`31`	`# == When to use streaming`
`37`	`32`	`#`
`38`		`- # Streaming may be considered to be overkill for lightweight actions like`
	`33`	`+ # \Streaming may be considered to be overkill for lightweight actions like`
`39`	`34`	`# +new+ or +edit+. The real benefit of streaming is on expensive actions`
`40`	`35`	`# that, for example, do a lot of queries on the database.`
`41`	`36`	`#`
`@@ -59,7 +54,7 @@ module ActionController # :nodoc:`
`59`	`54`	`# render stream: true`
`60`	`55`	`# end`
`61`	`56`	`#`
`62`		`- # Notice that +:stream+ only works with templates. Rendering +:json+`
	`57`	`+ # Notice that +:stream+ only works with templates. \Rendering +:json+`
`63`	`58`	`# or +:xml+ with +:stream+ won't work.`
`64`	`59`	`#`
`65`	`60`	`# == Communication between layout and template`
`@@ -112,7 +107,7 @@ module ActionController # :nodoc:`
`112`	`107`	`# This means that, if you have <code>yield :title</code> in your layout`
`113`	`108`	`# and you want to use streaming, you would have to render the whole template`
`114`	`109`	`# (and eventually trigger all queries) before streaming the title and all`
`115`		`- # assets, which kills the purpose of streaming. For this purpose, you can use`
	`110`	`+ # assets, which defeats the purpose of streaming. Alternatively, you can use`
`116`	`111`	`# a helper called +provide+ that does the same as +content_for+ but tells the`
`117`	`112`	`# layout to stop searching for other entries and continue rendering.`
`118`	`113`	`#`
`@@ -122,7 +117,7 @@ module ActionController # :nodoc:`
`122`	`117`	`# Hello`
`123`	`118`	`# <%= content_for :title, " page" %>`
`124`	`119`	`#`
`125`		`- # Giving:`
	`120`	`+ # Resulting in:`
`126`	`121`	`#`
`127`	`122`	`# <html>`
`128`	`123`	`# <head><title>Main</title></head>`
`@@ -132,6 +127,8 @@ module ActionController # :nodoc:`
`132`	`127`	`# That said, when streaming, you need to properly check your templates`
`133`	`128`	`# and choose when to use +provide+ and +content_for+.`
`134`	`129`	`#`
	`130`	`+ # See also ActionView::Helpers::CaptureHelper for more information.`
	`131`	`+ #`
`135`	`132`	`# == Headers, cookies, session, and flash`
`136`	`133`	`#`
`137`	`134`	`# When streaming, the HTTP headers are sent to the client right before`
`@@ -161,9 +158,9 @@ module ActionController # :nodoc:`
`161`	`158`	`#`
`162`	`159`	`# "><script>window.location = "/500.html"</script></html>`
`163`	`160`	`#`
`164`		`- # The first two characters (">) are required in case the exception happens`
`165`		`- # while rendering attributes for a given tag. You can check the real cause`
`166`		`- # for the exception in your logger.`
	`161`	`+ # The first two characters (<tt>"></tt>) are required in case the exception`
	`162`	`+ # happens while rendering attributes for a given tag. You can check the real`
	`163`	`+ # cause for the exception in your logger.`
`167`	`164`	`#`
`168`	`165`	`# == Web server support`
`169`	`166`	`#`
`@@ -183,11 +180,13 @@ module ActionController # :nodoc:`
`183`	`180`	`# unicorn_rails --config-file unicorn.config.rb`
`184`	`181`	`#`
`185`	`182`	`# You may also want to configure other parameters like <tt>:tcp_nodelay</tt>.`
	`183`	`+ #`
`186`	`184`	`# Please check its documentation for more information:`
`187`		`- # https://bogomips.org/unicorn/Unicorn/Configurator.html#method-i-listen`
	`185`	`+ #`
	`186`	`+ # * https://bogomips.org/unicorn/Unicorn/Configurator.html#method-i-listen`
`188`	`187`	`#`
`189`	`188`	`# If you are using Unicorn with NGINX, you may need to tweak NGINX.`
`190`		`- # Streaming should work out of the box on Rainbows.`
	`189`	`+ # \Streaming should work out of the box on Rainbows.`
`191`	`190`	`#`
`192`	`191`	`# ==== Passenger`
`193`	`192`	`#`
`@@ -203,7 +202,8 @@ module ActionController # :nodoc:`
`203`	`202`	`# the response back to the client.`
`204`	`203`	`#`
`205`	`204`	`# Please check the documentation for more information:`
`206`		`- # https://www.phusionpassenger.com/docs/references/config_reference/nginx/#passenger_buffer_response`
	`205`	`+ #`
	`206`	`+ # * https://www.phusionpassenger.com/docs/references/config_reference/nginx/#passenger_buffer_response`
`207`	`207`	`#`
`208`	`208`	`module Streaming`
`209`	`209`	`private`