From 4c22bdbcb75ecc8176e0f42899ed8c03729cc628 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Mon, 11 Dec 2017 11:00:47 +0100 Subject: Document 2.2 changes and the new stream_trailers function --- doc/src/manual/cowboy_req.asciidoc | 1 + doc/src/manual/cowboy_req.stream_body.asciidoc | 7 ++- doc/src/manual/cowboy_req.stream_reply.asciidoc | 5 +- doc/src/manual/cowboy_req.stream_trailers.asciidoc | 70 ++++++++++++++++++++++ doc/src/manual/cowboy_stream.asciidoc | 21 ++++++- 5 files changed, 99 insertions(+), 5 deletions(-) create mode 100644 doc/src/manual/cowboy_req.stream_trailers.asciidoc (limited to 'doc/src/manual') 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]. -- cgit v1.2.3