Document 2.2 changes and the new stream_trailers function

5 files changed, 99 insertions, 5 deletions

diff --git a/doc/src/manual/cowboy_req.asciidoc b/doc/src/manual/cowboy_req.asciidoc
index b2875bc..9378d2e 100644
--- a/doc/src/manual/cowboy_req.asciidoc
+++ b/doc/src/manual/cowboy_req.asciidoc
@@ -84,6 +84,7 @@ Response:
 * link:man:cowboy_req:reply(3)[cowboy_req:reply(3)] - Send the response
 * link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)] - Send the response headers
 * link:man:cowboy_req:stream_body(3)[cowboy_req:stream_body(3)] - Stream the response body
+* link:man:cowboy_req:stream_trailers(3)[cowboy_req:stream_trailers(3)] - Send the response trailers
 * link:man:cowboy_req:push(3)[cowboy_req:push(3)] - Push a resource to the client
 
 == Types
diff --git a/doc/src/manual/cowboy_req.stream_body.asciidoc b/doc/src/manual/cowboy_req.stream_body.asciidoc
index e0dbd59..17ba96f 100644
--- a/doc/src/manual/cowboy_req.stream_body.asciidoc
+++ b/doc/src/manual/cowboy_req.stream_body.asciidoc
@@ -24,7 +24,9 @@ function.
 The second argument indicates if this call is the final
 call. Use the `nofin` value until you know no more data
 will be sent. The final call should use `fin` (possibly
-with an empty data value).
+with an empty data value) or be a call to the
+link:man:cowboy_req:stream_trailers(3)[cowboy_req:stream_trailers(3)]
+function.
 
 Note that not using `fin` for the final call is not an
 error; Cowboy will take care of it when the request
@@ -74,4 +76,5 @@ cowboy_req:stream_body(<<"World!\n">>, fin, Req).
 == See also
 
 link:man:cowboy_req(3)[cowboy_req(3)],
-link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)]
+link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)],
+link:man:cowboy_req:stream_trailers(3)[cowboy_req:stream_trailers(3)]
diff --git a/doc/src/manual/cowboy_req.stream_reply.asciidoc b/doc/src/manual/cowboy_req.stream_reply.asciidoc
index 19d46ca..a00dbb0 100644
--- a/doc/src/manual/cowboy_req.stream_reply.asciidoc
+++ b/doc/src/manual/cowboy_req.stream_reply.asciidoc
@@ -34,7 +34,9 @@ If a response body was set before calling this function,
 it will not be sent.
 
 Use link:man:cowboy_req:stream_body(3)[cowboy_req:stream_body(3)]
-to stream the response body.
+to stream the response body and optionally
+link:man:cowboy_req:stream_trailers(3)[cowboy_req:stream_trailers(3)]
+to send response trailer field values.
 
 You may want to set the content-length header when using
 this function, if it is known in advance. This will allow
@@ -106,4 +108,5 @@ link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)],
 link:man:cowboy_req:inform(3)[cowboy_req:inform(3)],
 link:man:cowboy_req:reply(3)[cowboy_req:reply(3)],
 link:man:cowboy_req:stream_body(3)[cowboy_req:stream_body(3)],
+link:man:cowboy_req:stream_trailers(3)[cowboy_req:stream_trailers(3)],
 link:man:cowboy_req:push(3)[cowboy_req:push(3)]
diff --git a/doc/src/manual/cowboy_req.stream_trailers.asciidoc b/doc/src/manual/cowboy_req.stream_trailers.asciidoc
new file mode 100644
index 0000000..df74c3c
--- /dev/null
+++ b/doc/src/manual/cowboy_req.stream_trailers.asciidoc
@@ -0,0 +1,70 @@
+= cowboy_req:stream_trailers(3)
+
+== Name
+
+cowboy_req:stream_trailers - Send the response trailers
+
+== Description
+
+[source,erlang]
+----
+stream_trailers(Trailers, Req :: cowboy_req:req()) -> ok
+
+Trailers :: cowboy:http_headers()
+----
+
+Send the response trailers and terminate the stream.
+
+This function can only be called once, after initiating
+a response using
+link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)]
+and sending zero or more body chunks using
+link:man:cowboy_req:stream_body(3)[cowboy_req:stream_body(3)]
+with the `nofin` argument set. The function `stream_trailers/2`
+implies `fin` and automatically terminate the response.
+
+You must list all field names sent in trailers in the
+trailer header, otherwise they might be dropped by intermediaries
+or clients.
+
+== Arguments
+
+Trailers::
+
+Trailer field values to be sent.
+
+Req::
+
+The Req object.
+
+== Return value
+
+The atom `ok` is always returned. It can be safely ignored.
+
+== Changelog
+
+* *2.2*: Function introduced.
+
+== Examples
+
+.Stream a response body with trailers
+[source,erlang]
+----
+Req = cowboy_req:stream_reply(200, #{
+    <<"content-type">> => <<"text/plain">>,
+    <<"trailer">> => <<"expires, content-md5">>
+}, Req0),
+cowboy_req:stream_body(<<"Hello\n">>, nofin, Req),
+timer:sleep(1000),
+cowboy_req:stream_body(<<"World!\n">>, nofin, Req).
+cowboy_req:stream_trailers(#{
+    <<"expires">> => <<"Sun, 10 Dec 2017 19:13:47 GMT">>,
+    <<"content-md5">> => <<"fbf68a8e34b2ded53bba54e68794b4fe">>
+}, Req).
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)],
+link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_body(3)]
diff --git a/doc/src/manual/cowboy_stream.asciidoc b/doc/src/manual/cowboy_stream.asciidoc
index a26d420..103b97e 100644
--- a/doc/src/manual/cowboy_stream.asciidoc
+++ b/doc/src/manual/cowboy_stream.asciidoc
@@ -114,8 +114,8 @@ Initiate a response to the client.
 ----
 
 This initiates a response to the client. The stream
-will end when a data command with the `fin` flag is
-returned.
+will end when a data command with the `fin` flag or
+a trailer command is returned.
 
 [[data_command]]
 === data
@@ -127,6 +127,16 @@ Send data to the client.
 {data, fin(), iodata()}
 ----
 
+[[trailers_command]]
+=== trailers
+
+Send response trailers to the client.
+
+[source,erlang]
+----
+{trailers, cowboy:http_headers()}
+----
+
 [[push_command]]
 === push
 
@@ -286,6 +296,13 @@ 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].