Document cowboy_stream_h/cowboy_compress_h

doc/src/guide/migrating_from_2.5.asciidoc

@@ -24,6 +24,9 @@ experimental.
   data in order to compress them. This is the case for
   gzip compression.
 
+* The stream handlers `cowboy_stream_h` and
+  `cowboy_compress_h` are now documented.
+
 * Add the `chunked` option to allow disabling chunked
   transfer-encoding for HTTP/1.1 connections.
 

doc/src/manual/cowboy_app.asciidoc

@@ -32,6 +32,11 @@ Handlers:
 
 * link:man:cowboy_static(3)[cowboy_static(3)] - Static file handler
 
+Stream handlers:
+
+* link:man:cowboy_stream_h(3)[cowboy_stream_h(3)] - Default stream handler
+* link:man:cowboy_compress_h(3)[cowboy_compress_h(3)] - Compress stream handler
+
 Behaviors:
 
 * link:man:cowboy_handler(3)[cowboy_handler(3)] - Plain HTTP handlers

doc/src/manual/cowboy_compress_h.asciidoc

@@ -0,0 +1,60 @@
+= cowboy_compress_h(3)
+
+== Name
+
+cowboy_compress_h - Compress stream handler
+
+== Description
+
+The module `cowboy_compress_h` compresses response bodies
+automatically when the client supports it. It will not
+try to compress responses that already have a content
+encoding.
+
+Normal responses will only be compressed when their
+size is lower than the configured threshold. Streamed
+responses are always compressed, including when the
+sendfile command is used. Because the file must be
+read in memory to be compressed, this module is *not*
+suitable for automatically compressing large files.
+
+== Options
+
+[source,erlang]
+----
+opts() :: #{
+    compress_buffering => boolean(),
+    compress_threshold => non_neg_integer()
+}
+----
+
+Configuration for the default stream handler.
+
+The default value is given next to the option name:
+
+compress_buffering (false)::
+
+Whether the output will be buffered. By default no
+buffering is done to provide maximum compatibility
+at the cost of a lower compression rate.
+
+compress_threshold (300)::
+
+How large the response body must be to be compressed
+when the response isn't streamed.
+
+== Events
+
+The compress stream handler does not produce any event.
+
+== Changelog
+
+* *2.6*: The options `compress_buffering` and
+  `compress_threshold` were added.
+* *2.0*: Module introduced.
+
+== See also
+
+link:man:cowboy(7)[cowboy(7)],
+link:man:cowboy_stream(3)[cowboy_stream(3)],
+link:man:cowboy_stream_h(3)[cowboy_stream_h(3)]

doc/src/manual/cowboy_http.asciidoc

@@ -11,7 +11,7 @@ as a Ranch protocol.
 
 == Options
 
-// @todo Might be worth moving cowboy_clear/tls/stream_h options
+// @todo Might be worth moving cowboy_clear/tls options
 // to their respective manual, when they are added.
 
 [source,erlang]
@@ -19,7 +19,6 @@ as a Ranch protocol.
 opts() :: #{
     chunked                 => boolean(),
     connection_type         => worker | supervisor,
-    env                     => cowboy_middleware:env(),
     http10_keepalive        => boolean(),
     idle_timeout            => timeout(),
     inactivity_timeout      => timeout(),
@@ -32,11 +31,9 @@ opts() :: #{
     max_method_length       => non_neg_integer(),
     max_request_line_length => non_neg_integer(),
     max_skip_body_length    => non_neg_integer(),
-    middlewares             => [module()],
     proxy_header            => boolean(),
     request_timeout         => timeout(),
     sendfile                => boolean(),
-    shutdown_timeout        => timeout(),
     stream_handlers         => [module()]
 }
 ----
@@ -63,10 +60,6 @@ connection_type (supervisor)::
 
 Whether the connection process also acts as a supervisor.
 
-env (#{})::
-
-Middleware environment.
-
 http10_keepalive (true)::
 
 Whether keep-alive is enabled for HTTP/1.0 connections.
@@ -118,10 +111,6 @@ max_skip_body_length (1000000)::
 Maximum length Cowboy is willing to skip when the user code did not read the body fully.
 When the remaining length is too large or unknown Cowboy will close the connection.
 
-middlewares ([cowboy_router, cowboy_handler])::
-
-Middlewares to run for every request.
-
 proxy_header (false)::
 
 Whether incoming connections have a PROXY protocol header. The
@@ -138,10 +127,6 @@ Whether the sendfile syscall may be used. It can be useful to disable
 it on systems where the syscall has a buggy implementation, for example
 under VirtualBox when using shared folders.
 
-shutdown_timeout (5000)::
-
-Time in ms Cowboy will wait for child processes to shut down before killing them.
-
 stream_handlers ([cowboy_stream_h])::
 
 Ordered list of stream handlers that will handle all stream events.

doc/src/manual/cowboy_http2.asciidoc

@@ -19,7 +19,6 @@ as a Ranch protocol.
 opts() :: #{
     connection_type                => worker | supervisor,
     enable_connect_protocol        => boolean(),
-    env                            => cowboy_middleware:env(),
     idle_timeout                   => timeout(),
     inactivity_timeout             => timeout(),
     initial_connection_window_size => 65535..16#7fffffff,
@@ -29,12 +28,10 @@ opts() :: #{
     max_encode_table_size          => non_neg_integer(),
     max_frame_size_received        => 16384..16777215,
     max_frame_size_sent            => 16384..16777215 | infinity,
-    middlewares                    => [module()],
     preface_timeout                => timeout(),
     proxy_header                   => boolean(),
     sendfile                       => boolean(),
     settings_timeout               => timeout(),
-    shutdown_timeout               => timeout(),
     stream_handlers                => [module()]
 }
 ----
@@ -60,10 +57,6 @@ Whether to enable the extended CONNECT method to allow
 protocols like Websocket to be used over an HTTP/2 stream.
 This option is experimental and disabled by default.
 
-env (#{})::
-
-Middleware environment.
-
 idle_timeout (60000)::
 
 Time in ms with no data received before Cowboy closes the connection.
@@ -118,10 +111,6 @@ following the client's advertised maximum.
 Note that actual frame sizes may be lower than the limit when
 there is not enough space left in the flow control window.
 
-middlewares ([cowboy_router, cowboy_handler])::
-
-Middlewares to run for every request.
-
 preface_timeout (5000)::
 
 Time in ms Cowboy is willing to wait for the connection preface.
@@ -142,10 +131,6 @@ settings_timeout (5000)::
 
 Time in ms Cowboy is willing to wait for a SETTINGS ack.
 
-shutdown_timeout (5000)::
-
-Time in ms Cowboy will wait for child processes to shut down before killing them.
-
 stream_handlers ([cowboy_stream_h])::
 
 Ordered list of stream handlers that will handle all stream events.

doc/src/manual/cowboy_stream.asciidoc

@@ -21,7 +21,7 @@ protocol.
 Extra care must be taken when implementing stream handlers
 to ensure compatibility. While some modification of the
 events and commands is allowed, it is generally not a good
-idea to completely omit them.
+idea to completely discard them.
 
 == Callbacks
 
@@ -256,74 +256,19 @@ then forward `Msg` to the stream handlers.
 Cowboy will also forward the exit signals for the
 processes that the stream spawned.
 
-=== EXIT
-
-//info(_StreamID, {'EXIT', Pid, normal}, State=#state{pid=Pid}) ->
-//info(_StreamID, {'EXIT', Pid, {_Reason, [_, {cow_http_hd, _, _, _}|_]}}, State=#state{pid=Pid}) ->
-//info(StreamID, Exit = {'EXIT', Pid, {Reason, Stacktrace}}, State=#state{ref=Ref, pid=Pid}) ->
-
-A process spawned by this stream has exited.
-
-[source,erlang]
-----
-{'EXIT', pid(), any()}
-----
-
-This is the raw exit message without any modification.
-
-// === read_body
-// 
-// //info(_StreamID, {read_body, Ref, Length, _},
-// //info(StreamID, {read_body, Ref, Length, Period}, State) ->
-// 
-// TODO yeah I am not actually sure this one should be public just yet
-
-=== inform
-
-Same as the xref:inform_command[inform command].
-
-Sent when the request process reads the body and an
-expect: 100-continue header was present in the request,
-or when the request process sends an informational
-response on its own.
-
-=== response
-
-Same as the xref:response_command[response command].
-
-Usually sent when the request process replies to the client.
-May also be sent by Cowboy internally.
-
-=== headers
-
-Same as the xref:headers_command[headers command].
-
-Sent when the request process starts replying to the client.
-
-=== data
-
-Same as the xref:data_command[data command].
-
-Sent when the request process streams data to the client.
-
-=== trailers
-
-Same as the xref:trailers_command[trailers command].
-
-Sent when the request process sends the trailer field values
-to the client.
-
-=== push
-
-Same as the xref:push_command[push command].
-
-Sent when the request process pushes a resource to the client.
-
-=== switch_protocol
-
-Same as the xref:switch_protocol_command[switch_protocol command].
-
-Sent when switching to the HTTP/2 or Websocket protocol.
+When Cowboy needs to send a response it will trigger
+an event that looks exactly like the corresponding
+command. This event must be returned to be processed
+by Cowboy (which is done automatically when using
+link:man:cowboy_stream_h(3)[cowboy_stream_h(3)]).
+
+Cowboy may trigger the following events on its own,
+regardless of the stream handlers configured:
+xref:inform_command[inform] (to send a 101
+informational response when upgrading to HTTP/2 or
+Websocket), xref:response_command[response],
+xref:headers_command[headers], xref:data_command[data]
+and xref:switch_protocol_command[switch_protocol].
 
 == Exports
 

doc/src/manual/cowboy_stream_h.asciidoc

@@ -0,0 +1,71 @@
+= cowboy_stream_h(3)
+
+== Name
+
+cowboy_stream_h - Default stream handler
+
+== Description
+
+The module `cowboy_stream_h` is Cowboy's default stream
+handler and defines much of its behavior. It is responsible
+for managing the request process, sending it the request
+body and translating its messages into commands that
+Cowboy understands.
+
+== Options
+
+[source,erlang]
+----
+opts() :: #{
+    env              => cowboy_middleware:env(),
+    middlewares      => [module()],
+    shutdown_timeout => timeout()
+}
+----
+
+Configuration for the default stream handler.
+
+The default value is given next to the option name:
+
+env (#{})::
+
+Middleware environment.
+
+middlewares ([cowboy_router, cowboy_handler])::
+
+Middlewares to run for every request.
+
+shutdown_timeout (5000)::
+
+Time in ms Cowboy will wait for child processes to shut down before killing them.
+
+== Events
+
+The default stream handler spawns the request process
+and receives its exit signal when it terminates. It
+will stop the stream once its receives it.
+
+// @todo It also implements the read_body mechanism.
+// Note that cowboy_stream_h sends the 100-continue automatically.
+
+In addition it returns a command for any event message
+looking like one of the following commands: `inform`,
+`response`, `headers`, `data`, `trailers`, `push`,
+`switch_protocol`. This is what allows the request
+process to send a response.
+
+// @todo Add set_options, which updates options dynamically.
+
+Because this stream handler converts events from the
+request process into commands, other stream handlers
+may not work properly if they are executed
+
+== Changelog
+
+* *2.0*: Module introduced.
+
+== See also
+
+link:man:cowboy(7)[cowboy(7)],
+link:man:cowboy_stream(3)[cowboy_stream(3)],
+link:man:cowboy_compress_h(3)[cowboy_compress_h(3)]