aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/guide
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2017-01-02 14:20:15 +0100
committerLoïc Hoguin <[email protected]>2017-01-02 14:46:19 +0100
commit271e31c629be2dff93d68e01c9a8a9c5c34b7e2c (patch)
treeb20ba4f01a174479c1cde0d7abb610dbfa757d05 /doc/src/guide
parent5838a0c81a978377084b33fd086de10f9775f425 (diff)
downloadcowboy-271e31c629be2dff93d68e01c9a8a9c5c34b7e2c.tar.gz
cowboy-271e31c629be2dff93d68e01c9a8a9c5c34b7e2c.tar.bz2
cowboy-271e31c629be2dff93d68e01c9a8a9c5c34b7e2c.zip
Various fixes and tweaks to the user guide
Diffstat (limited to 'doc/src/guide')
-rw-r--r--doc/src/guide/book.asciidoc36
-rw-r--r--doc/src/guide/flow_diagram.asciidoc8
-rw-r--r--doc/src/guide/handlers.asciidoc9
-rw-r--r--doc/src/guide/listeners.asciidoc2
-rw-r--r--doc/src/guide/loop_handlers.asciidoc15
-rw-r--r--doc/src/guide/multipart.asciidoc2
-rw-r--r--doc/src/guide/rest_handlers.asciidoc8
-rw-r--r--doc/src/guide/streams.asciidoc15
8 files changed, 66 insertions, 29 deletions
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]