From faefb634de2874cafaf7f2d7fb7d4f8eab9019a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 27 Jun 2018 10:29:49 +0200 Subject: Document cowboy_req:stream_events/3 --- doc/src/manual/cowboy_req.asciidoc | 1 + doc/src/manual/cowboy_req.stream_body.asciidoc | 1 + doc/src/manual/cowboy_req.stream_events.asciidoc | 101 +++++++++++++++++++++ doc/src/manual/cowboy_req.stream_reply.asciidoc | 1 + doc/src/manual/cowboy_req.stream_trailers.asciidoc | 3 +- 5 files changed, 106 insertions(+), 1 deletion(-) create mode 100644 doc/src/manual/cowboy_req.stream_events.asciidoc diff --git a/doc/src/manual/cowboy_req.asciidoc b/doc/src/manual/cowboy_req.asciidoc index 9378d2e..309aedf 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_events(3)[cowboy_req:stream_events(3)] - Stream events * 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 diff --git a/doc/src/manual/cowboy_req.stream_body.asciidoc b/doc/src/manual/cowboy_req.stream_body.asciidoc index 17ba96f..24f5d97 100644 --- a/doc/src/manual/cowboy_req.stream_body.asciidoc +++ b/doc/src/manual/cowboy_req.stream_body.asciidoc @@ -77,4 +77,5 @@ cowboy_req:stream_body(<<"World!\n">>, fin, Req). 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_events(3)[cowboy_req:stream_events(3)], link:man:cowboy_req:stream_trailers(3)[cowboy_req:stream_trailers(3)] diff --git a/doc/src/manual/cowboy_req.stream_events.asciidoc b/doc/src/manual/cowboy_req.stream_events.asciidoc new file mode 100644 index 0000000..72f3c3b --- /dev/null +++ b/doc/src/manual/cowboy_req.stream_events.asciidoc @@ -0,0 +1,101 @@ += cowboy_req:stream_events(3) + +== Name + +cowboy_req:stream_events - Stream events + +== Description + +[source,erlang] +---- +stream_events(Events, IsFin, Req :: cowboy_req:req()) -> ok + +Events :: Event | [Event] +IsFin :: fin | nofin + +Event :: #{ + comment => iodata(), + data => iodata(), + event => iodata() | atom(), + id => iodata(), + retry => non_neg_integer() +} +---- + +Stream events. + +This function should only be used for `text/event-stream` +responses when using server-sent events. Cowboy will +automatically encode the given events to their text +representation. + +This function may be called as many times as needed after +initiating a response using the +link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)] +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) 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 +handler terminates if needed. Depending on the resource +it may however be more efficient to do it as early as +possible. + +You do not need to handle HEAD requests specifically as +Cowboy will ensure no data is sent when you call this function. + +== Arguments + +Events:: + +Events to be sent. All fields are optional. + +IsFin:: + +A flag indicating whether this is the final piece of data +to be sent. + +Req:: + +The Req object. + +== Return value + +The atom `ok` is always returned. It can be safely ignored. + +== Changelog + +* *2.5*: Function introduced. + +== Examples + +.Stream events +[source,erlang] +---- +Req = cowboy_req:stream_reply(200, #{ + <<"content-type">> => <<"text/event-stream">> +}, Req0), +cowboy_req:stream_events(#{ + id => <<"comment-123">>, + event => <<"add_comment">>, + data => <<"Hello,\n\nI noticed something wrong in ...">> +}, nofin, Req), +timer:sleep(1000), +cowboy_req:stream_events(#{ + event => <<"debug">>, + data => io_lib:format("An error occurred: ~p~n", [Error]) +}, 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_body(3)[cowboy_req:stream_body(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 82f49c6..2242908 100644 --- a/doc/src/manual/cowboy_req.stream_reply.asciidoc +++ b/doc/src/manual/cowboy_req.stream_reply.asciidoc @@ -110,5 +110,6 @@ 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_events(3)[cowboy_req:stream_events(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 index 6549372..6d48e18 100644 --- a/doc/src/manual/cowboy_req.stream_trailers.asciidoc +++ b/doc/src/manual/cowboy_req.stream_trailers.asciidoc @@ -67,4 +67,5 @@ cowboy_req:stream_trailers(#{ 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_body(3)[cowboy_req:stream_body(3)] +link:man:cowboy_req:stream_body(3)[cowboy_req:stream_body(3)], +link:man:cowboy_req:stream_events(3)[cowboy_req:stream_events(3)] -- cgit v1.2.3