aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2017-12-11 12:43:14 +0100
committerLoïc Hoguin <[email protected]>2017-12-11 12:43:14 +0100
commit364a3527d4d096aebdf4d59ece1b2b660e6ed846 (patch)
treea8095547703a70aae78fc6a6671cd133a9c26fb0
parent6d65cd0d3889e7f21d8f5b077e3c140ddb090006 (diff)
downloadcowboy-364a3527d4d096aebdf4d59ece1b2b660e6ed846.tar.gz
cowboy-364a3527d4d096aebdf4d59ece1b2b660e6ed846.tar.bz2
cowboy-364a3527d4d096aebdf4d59ece1b2b660e6ed846.zip
Document trailers in the guide
-rw-r--r--doc/src/guide/resp.asciidoc30
1 files changed, 29 insertions, 1 deletions
diff --git a/doc/src/guide/resp.asciidoc b/doc/src/guide/resp.asciidoc
index 6d4967e..781157d 100644
--- a/doc/src/guide/resp.asciidoc
+++ b/doc/src/guide/resp.asciidoc
@@ -128,7 +128,35 @@ in advance. This will ensure that the best response method
is selected and help clients understand when the response
is fully received.
-// @todo Document trailers here.
+Cowboy also provides a function to send response trailers.
+Response trailers are semantically equivalent to the headers
+you send in the response, only they are sent at the end.
+This is especially useful to attach information to the
+response that could not be generated until the response
+body was fully generated.
+
+Trailer fields must be listed in the trailer header. Any
+field not listed might be dropped by the client or an intermediary.
+
+[source,erlang]
+----
+Req = cowboy_req:stream_reply(200, #{
+ <<"content-type">> => <<"text/html">>,
+ <<"trailer">> => <<"expires, content-md5">>
+}, Req0),
+
+cowboy_req:stream_body("<html><head>Hello world!</head>", nofin, Req),
+cowboy_req:stream_body("<body><p>Hats off!</p></body></html>", nofin, Req),
+
+cowboy_req:stream_trailers(#{
+ <<"expires">> => <<"Sun, 10 Dec 2017 19:13:47 GMT">>,
+ <<"content-md5">> => <<"c6081d20ff41a42ce17048ed1c0345e2">>
+}, Req).
+----
+
+The stream ends with trailers. It is no longer possible to
+send data after sending trailers. You cannot send trailers
+after setting the `fin` flag when streaming the body.
=== Preset response headers