From 364a3527d4d096aebdf4d59ece1b2b660e6ed846 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Mon, 11 Dec 2017 12:43:14 +0100 Subject: Document trailers in the guide --- doc/src/guide/resp.asciidoc | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) 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("Hello world!", nofin, Req), +cowboy_req:stream_body("

Hats off!

", 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 -- cgit v1.2.3