From 271e31c629be2dff93d68e01c9a8a9c5c34b7e2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Mon, 2 Jan 2017 14:20:15 +0100 Subject: Various fixes and tweaks to the user guide --- doc/src/guide/book.asciidoc | 36 ++++++++++++++++++++++++------------ doc/src/guide/flow_diagram.asciidoc | 8 ++++++++ doc/src/guide/handlers.asciidoc | 9 ++++----- doc/src/guide/listeners.asciidoc | 2 +- doc/src/guide/loop_handlers.asciidoc | 15 +++++++++------ doc/src/guide/multipart.asciidoc | 2 +- doc/src/guide/rest_handlers.asciidoc | 8 ++++---- doc/src/guide/streams.asciidoc | 15 +++++++++++++++ 8 files changed, 66 insertions(+), 29 deletions(-) create mode 100644 doc/src/guide/streams.asciidoc (limited to 'doc/src/guide') diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc index 9c5f49e..3fdb3b7 100644 --- a/doc/src/guide/book.asciidoc +++ b/doc/src/guide/book.asciidoc @@ -21,16 +21,12 @@ include::introduction.asciidoc[Introduction] include::getting_started.asciidoc[Getting started] -// NEW! Flow diagram here -// MERGE include::overview.asciidoc[Request overview] include::flow_diagram.asciidoc[Flow diagram] = Configuration include::listeners.asciidoc[Listeners] -include::streams.asciidoc[Streams] - include::routing.asciidoc[Routing] include::constraints.asciidoc[Constraints] @@ -69,19 +65,35 @@ include::resource_design.asciidoc[Designing a resource handler] include::ws_protocol.asciidoc[The Websocket protocol] -include::ws_handlers.asciidoc[Handling Websocket connections] +include::ws_handlers.asciidoc[Websocket handlers] -= Internals += Advanced -// TODO: shouldn't be needed anymore? -include::architecture.asciidoc[Architecture] - -// TODO: Move into Common scenarios or something; switch to streams -include::broken_clients.asciidoc[Dealing with broken clients] +include::streams.asciidoc[Streams] include::middlewares.asciidoc[Middlewares] +// @todo Rather have two chapters, custom handlers and custom protocol upgrades include::sub_protocols.asciidoc[Sub protocols] -// TODO: they're gone +//= Additional information + +//include::migrating_from_1.0.asciidoc[Migrating from Cowboy 1.0 to 2.0] + +// @todo Maybe history? Could take info from architecture also. + += Deprecated chapters + +== About the deprecated chapters + +The following chapters were relevant in Cowboy 1.0. They have +not been updated for Cowboy 2.0 yet. The information in these +chapters may or may not be useful. + +include::architecture.asciidoc[Architecture] + +include::broken_clients.asciidoc[Dealing with broken clients] + include::hooks.asciidoc[Hooks] + +include::overview.asciidoc[Overview] diff --git a/doc/src/guide/flow_diagram.asciidoc b/doc/src/guide/flow_diagram.asciidoc index 1095404..ad2110d 100644 --- a/doc/src/guide/flow_diagram.asciidoc +++ b/doc/src/guide/flow_diagram.asciidoc @@ -2,3 +2,11 @@ == Flow diagram Placeholder chapter. + +Cowboy 2.0 has changed the request flow and general architecture. +You can read about the Cowboy 1.0 architecture and flow here: + +* xref:architecture[Architecture] +* xref:overview[Overview] + +This chapter will be updated in a future pre-release. diff --git a/doc/src/guide/handlers.asciidoc b/doc/src/guide/handlers.asciidoc index 88fbc21..e073dfb 100644 --- a/doc/src/guide/handlers.asciidoc +++ b/doc/src/guide/handlers.asciidoc @@ -29,9 +29,9 @@ We need to use the Req object to reply. [source,erlang] ---- init(Req0, State) -> - Req = cowboy_req:reply(200, [ - {<<"content-type">>, <<"text/plain">>} - ], <<"Hello World!">>, Req0), + Req = cowboy_req:reply(200, #{ + <<"content-type">> => <<"text/plain">> + }, <<"Hello World!">>, Req0), {ok, Req, State}. ---- @@ -81,8 +81,7 @@ xref:sub_protocols[Sub protocols] chapter. === Cleaning up -With the exception of Websocket handlers, all handler types -provide the optional `terminate/3` callback. +All handler types provide the optional `terminate/3` callback. [source,erlang] ---- diff --git a/doc/src/guide/listeners.asciidoc b/doc/src/guide/listeners.asciidoc index 901b922..7d5faec 100644 --- a/doc/src/guide/listeners.asciidoc +++ b/doc/src/guide/listeners.asciidoc @@ -7,7 +7,7 @@ Depending on the connection handshake, one or another protocol may be used. This chapter is specific to Cowboy. Please refer to the -http://ninenines.eu/docs/en/ranch/1.2/guide/listeners/[Ranch User Guide] +http://ninenines.eu/docs/en/ranch/1.3/guide/listeners/[Ranch User Guide] for more information about listeners. Cowboy provides two types of listeners: one listening for diff --git a/doc/src/guide/loop_handlers.asciidoc b/doc/src/guide/loop_handlers.asciidoc index c0195ea..2c82c53 100644 --- a/doc/src/guide/loop_handlers.asciidoc +++ b/doc/src/guide/loop_handlers.asciidoc @@ -16,7 +16,7 @@ most known example of such practice is known as long polling. Loop handlers can also be used for requests where a response is partially available and you need to stream the response body while the connection is open. The most known example of such -practice is known as server-sent events. +practice is server-sent events. While the same can be accomplished using plain HTTP handlers, it is recommended to use loop handlers because they are well-tested @@ -66,7 +66,7 @@ message otherwise. [source,erlang] ---- info({reply, Body}, Req, State) -> - cowboy_req:reply(200, [], Body, Req), + cowboy_req:reply(200, #{}, Body, Req), {stop, Req, State}; info(_Msg, Req, State) -> {ok, Req, State, hibernate}. @@ -96,19 +96,19 @@ This can be done by initiating a chunked reply in the every time a message is received. The following snippet does exactly that. As you can see -a chunk is sent every time a `chunk` message is received, +a chunk is sent every time an `event` message is received, and the loop is stopped by sending an `eof` message. [source,erlang] ---- init(Req, State) -> - Req2 = cowboy_req:chunked_reply(200, [], Req), + Req2 = cowboy_req:stream_reply(200, Req), {cowboy_loop, Req2, State}. info(eof, Req, State) -> {stop, Req, State}; -info({chunk, Chunk}, Req, State) -> - cowboy_req:chunk(Chunk, Req), +info({event, Data}, Req, State) -> + cowboy_req:stream_body(Data, nofin, Req), {ok, Req, State}; info(_Msg, Req, State) -> {ok, Req, State}. @@ -125,6 +125,9 @@ for general instructions about cleaning up. === Timeout +Note that this feature currently does not work. It will be +brought back in a future 2.0 pre-release. + By default Cowboy will not attempt to close the connection if there is no activity from the client. This is not always desirable, which is why you can set a timeout. Cowboy will diff --git a/doc/src/guide/multipart.asciidoc b/doc/src/guide/multipart.asciidoc index 630b210..77d263a 100644 --- a/doc/src/guide/multipart.asciidoc +++ b/doc/src/guide/multipart.asciidoc @@ -146,7 +146,7 @@ all bodies: [source,erlang] ---- multipart(Req0) -> - case cowboy_req:part(Req0) of + case cowboy_req:read_part(Req0) of {ok, _Headers, Req} -> multipart(Req); {done, Req} -> diff --git a/doc/src/guide/rest_handlers.asciidoc b/doc/src/guide/rest_handlers.asciidoc index 748fca4..c69f02b 100644 --- a/doc/src/guide/rest_handlers.asciidoc +++ b/doc/src/guide/rest_handlers.asciidoc @@ -101,13 +101,13 @@ and in the second case that we send one as HTML. === Meta data -Cowboy will set informative meta values at various points of the -execution. You can retrieve them using `cowboy_req:meta/{2,3}`. -The values are defined in the following table. +Cowboy will set informative values to the Req object at various +points of the execution. You can retrieve them by matching the +Req object directly. The values are defined in the following table: [cols="<,<",options="header"] |=== -| Meta key | Details +| Key | Details | media_type | The content-type negotiated for the response entity. | language | The language negotiated for the response entity. | charset | The charset negotiated for the response entity. diff --git a/doc/src/guide/streams.asciidoc b/doc/src/guide/streams.asciidoc new file mode 100644 index 0000000..243e581 --- /dev/null +++ b/doc/src/guide/streams.asciidoc @@ -0,0 +1,15 @@ +[[streams]] +== Streams + +Placeholder chapter. + +Streams are a new feature in Cowboy 2.0 that requires +a little more tweaking before they can be generally +useful. This chapter will be made available in a future +pre-release. + +Streams are meant to replace hooks. The relevant chapters +for Cowboy 1.0 were: + +* xref:hooks[Hooks] +* xref:broken_clients[Dealing with broken clients] -- cgit v1.2.3