aboutsummaryrefslogtreecommitdiffstats
path: root/guide
diff options
context:
space:
mode:
Diffstat (limited to 'guide')
-rw-r--r--guide/http_req_life.md153
-rw-r--r--guide/http_req_resp.pngbin0 -> 33228 bytes
-rw-r--r--guide/http_req_resp.svg558
-rw-r--r--guide/toc.md142
4 files changed, 779 insertions, 74 deletions
diff --git a/guide/http_req_life.md b/guide/http_req_life.md
new file mode 100644
index 0000000..1462b59
--- /dev/null
+++ b/guide/http_req_life.md
@@ -0,0 +1,153 @@
+The life of a request
+=====================
+
+This chapter explains the different steps a request
+goes through until a response is sent, along with
+details of the Cowboy implementation.
+
+Request/response
+----------------
+
+As you already know, HTTP clients connect to the server and
+send a request for a resource; the server then sends a
+response containing the resource if it could obtain it.
+
+Before the server can send the resource, however, it
+needs to perform many different operations to read the
+request, find the resource, prepare the response being
+sent and often other related operations the user can
+add like writing logs.
+
+Requests take the following route in Cowboy:
+
+![HTTP request/response flowchart](http_req_resp.png)
+
+This shows the default middlewares, but they may be
+configured differently in your setup. The dark green
+indicates the points where you can hook your own code,
+the light green is the Cowboy code that you can of
+course configure as needed.
+
+The `acceptor` is the part of the server that accepts
+the connection and create an Erlang process to handle
+it. The `parser` then starts reading from the socket
+and handling requests as they come until the socket
+is closed.
+
+A response may be sent at many different points in the
+life of the request. If Cowboy can't parse the request,
+it gives up with an error response. If the router can't
+find the resource, it sends a not found error. Your
+own code can of course send a response at any time.
+
+When a response is sent, you can optionally modify it
+or act upon it by enabling the `onresponse` hook. By
+default the response is sent directly to the client.
+
+And then?
+---------
+
+Behavior depends on what protocol is in use.
+
+HTTP/1.0 can only process one request per connection,
+so Cowboy will close the connection immediately after
+it sends the response.
+
+HTTP/1.1 allows the client to request that the server
+keeps the connection alive. This mechanism is described
+in the next section.
+
+SPDY is designed to allow sending multiple requests
+asynchronously on the same connection. Details on what
+this means for your application is described in this
+chapter.
+
+Keep-alive (HTTP/1.1)
+---------------------
+
+With HTTP/1.1, the connection may be left open for
+subsequent requests to come. This mechanism is called
+`keep-alive`.
+
+When the client sends a request to the server, it includes
+a header indicating whether it would like to leave the
+socket open. The server may or may not accept, indicating
+its choice by sending the same header in the response.
+
+Cowboy will include this header automatically in all
+responses to HTTP/1.1 requests. You can however force
+the closing of the socket if you want. When Cowboy sees
+you want to send a `connection: close` header, it will
+not override it and will close the connection as soon
+as the reply is sent.
+
+This snippet will force Cowboy to close the connection.
+
+``` erlang
+{ok, Req2} = cowboy_req:reply(200, [
+ {<<"connection">>, <<"close">>},
+], <<"Closing the socket in 3.. 2.. 1..">>, Req).
+```
+
+Cowboy will only accept a certain number of new requests
+on the same connection. By default it will run up to 100
+requests. This number can be changed by setting the
+`max_keepalive` configuration value when starting an
+HTTP listener.
+
+``` erlang
+cowboy:start_http(my_http_listener, 100, [{port, 8080}], [
+ {env, [{dispatch, Dispatch}]},
+ {max_keepalive, 5}
+]).
+```
+
+Cowboy implements the keep-alive mechanism by reusing
+the same process for all requests. This allows Cowboy
+to save memory. This works well because most code will
+not have any side effect impacting subsequent requests.
+But it also means you need to clean up if you do have
+code with side effects. The `terminate/3` function can
+be used for this purpose.
+
+Pipelining (HTTP/1.1)
+---------------------
+
+While HTTP is designed as a sequential protocol, with
+the client sending a request and then waiting for the
+response from the server, nothing prevents the client
+from sending more requests to the server without waiting
+for the response, due to how sockets work. The server
+still handles the requests sequentially and sends the
+responses in the same order.
+
+This mechanism is called pipelining. It allows reducing
+latency when a client needs to request many resources
+at the same time. This is used by browsers when requesting
+static files for example.
+
+This is handled automatically by the server.
+
+Asynchronous requests (SPDY)
+----------------------------
+
+In SPDY, the client can send a request at any time.
+And the server can send a response at any time too.
+
+This means for example that the client does not need
+to wait for a request to be fully sent to send another,
+it is possible to interleave a request with the request
+body of another request. The same is true with responses.
+Responses may also be sent in a different order.
+
+Because requests and responses are fully asynchronous,
+Cowboy creates a new process for each request, and these
+processes are managed by another process that handles the
+connection itself.
+
+SPDY servers may also decide to send resources to the
+client before the client requests them. This is especially
+useful for sending static files associated with the HTML
+page requested, as this reduces the latency of the overall
+response. Cowboy does not support this particular mechanism
+at this point, however.
diff --git a/guide/http_req_resp.png b/guide/http_req_resp.png
new file mode 100644
index 0000000..e38935f
--- /dev/null
+++ b/guide/http_req_resp.png
Binary files differ
diff --git a/guide/http_req_resp.svg b/guide/http_req_resp.svg
new file mode 100644
index 0000000..0cfa0ae
--- /dev/null
+++ b/guide/http_req_resp.svg
@@ -0,0 +1,558 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:osb="http://www.openswatchbook.org/uri/2009/osb"
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="744.09448819"
+ height="1052.3622047"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.4 r9939"
+ sodipodi:docname="http_req_resp.svg"
+ inkscape:export-filename="/home/essen/Dropbox/Public/drawing.png"
+ inkscape:export-xdpi="90"
+ inkscape:export-ydpi="90">
+ <defs
+ id="defs4">
+ <linearGradient
+ id="linearGradient5265">
+ <stop
+ style="stop-color:#69d2e7;stop-opacity:1;"
+ offset="0"
+ id="stop5267" />
+ <stop
+ style="stop-color:#69d2e7;stop-opacity:0.58823532;"
+ offset="1"
+ id="stop5269" />
+ </linearGradient>
+ <linearGradient
+ id="linearGradient5251">
+ <stop
+ style="stop-color:#69d2e7;stop-opacity:0.78431374;"
+ offset="0"
+ id="stop5253" />
+ <stop
+ id="stop5263"
+ offset="0.5"
+ style="stop-color:#69d2e7;stop-opacity:1;" />
+ <stop
+ style="stop-color:#69d2e7;stop-opacity:0.39215687;"
+ offset="1"
+ id="stop5255" />
+ </linearGradient>
+ <linearGradient
+ id="linearGradient5233"
+ osb:paint="solid">
+ <stop
+ style="stop-color:#69d2e7;stop-opacity:1;"
+ offset="0"
+ id="stop5235" />
+ </linearGradient>
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="1"
+ inkscape:pageshadow="2"
+ inkscape:zoom="1.4142136"
+ inkscape:cx="229.71447"
+ inkscape:cy="764.83183"
+ inkscape:document-units="px"
+ inkscape:current-layer="layer1"
+ showgrid="false"
+ inkscape:window-width="1920"
+ inkscape:window-height="1014"
+ inkscape:window-x="0"
+ inkscape:window-y="33"
+ inkscape:window-maximized="1"
+ inkscape:snap-global="true"
+ showguides="true">
+ <inkscape:grid
+ type="xygrid"
+ id="grid5357"
+ empspacing="5"
+ visible="true"
+ enabled="true"
+ snapvisiblegridlinesonly="true" />
+ </sodipodi:namedview>
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title></dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1">
+ <use
+ x="0"
+ y="0"
+ xlink:href="#path5757"
+ id="use5779"
+ transform="matrix(0.59961275,-0.80029029,0.80029029,0.59961275,-103.8895,437.48518)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#path5757"
+ id="use5777"
+ transform="matrix(0.92125726,-0.38895379,0.38895379,0.92125726,-85.14742,176.0134)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <path
+ style="fill:none;stroke:#6d8e41;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:2, 4;stroke-dashoffset:0"
+ d="m 188.5,231.36218 187,79"
+ id="path5757"
+ inkscape:connector-curvature="0"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#g5650"
+ id="use5753"
+ transform="translate(475.11201,-33.017248)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#use5753"
+ id="use5755"
+ transform="translate(3.984568e-6,86.977569)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <rect
+ style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:2.44279908999999984;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect5367"
+ width="207.05719"
+ height="171.55719"
+ x="43.721401"
+ y="360.88528"
+ rx="11.072577"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#g5650"
+ id="use5654"
+ transform="translate(205.03261,53.351708)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#use5656"
+ id="use5658"
+ transform="translate(0,-86.13396)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#use5658"
+ id="use5660"
+ transform="translate(0,-87.519558)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#use5660"
+ id="use5662"
+ transform="translate(0,-86.562562)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <g
+ id="g5650">
+ <path
+ inkscape:connector-curvature="0"
+ id="path5570"
+ d="m -57.78256,351.41962 0,52.3259"
+ style="fill:none;stroke:#6d8e41;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;opacity:0.8" />
+ <path
+ transform="matrix(0.58787746,0,0,0.58787746,73.160466,163.35774)"
+ inkscape:transform-center-y="2.1823437"
+ d="m -222.73865,430.10821 -12.85982,-22.27386 25.71964,0 z"
+ inkscape:randomized="0"
+ inkscape:rounded="0"
+ inkscape:flatsided="true"
+ sodipodi:arg2="2.6179939"
+ sodipodi:arg1="1.5707963"
+ sodipodi:r2="7.4246211"
+ sodipodi:r1="14.849242"
+ sodipodi:cy="415.25897"
+ sodipodi:cx="-222.73865"
+ sodipodi:sides="3"
+ id="path5576"
+ style="fill:#6d8e41;fill-opacity:1;fill-rule:nonzero;stroke:#6d8e41;stroke-width:0;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;opacity:0.8"
+ sodipodi:type="star" />
+ </g>
+ <use
+ x="0"
+ y="0"
+ xlink:href="#use5654"
+ id="use5656"
+ transform="translate(6.1542801e-7,-87.19819)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <rect
+ style="fill:#d1f2a5;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect5273"
+ width="104.5895"
+ height="36.392323"
+ x="-224.02068"
+ y="29.41218"
+ rx="15" />
+ <rect
+ style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect5273-7"
+ width="104.5895"
+ height="36.392323"
+ x="-224.02068"
+ y="90.691978"
+ rx="15" />
+ <rect
+ style="fill:#ffc48c;fill-opacity:1;fill-rule:nonzero;stroke:#d79c64;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect5273-2"
+ width="104.5895"
+ height="36.392323"
+ x="-224.02068"
+ y="151.97169"
+ rx="15" />
+ <rect
+ style="fill:#ff9f80;fill-opacity:1;fill-rule:nonzero;stroke:#d77758;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect5273-22"
+ width="104.5895"
+ height="36.392323"
+ x="-224.02068"
+ y="213.25146"
+ rx="15" />
+ <rect
+ style="fill:#f56991;fill-opacity:1;fill-rule:nonzero;stroke:#cd4169;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+ id="rect5273-8"
+ width="104.5895"
+ height="36.392323"
+ x="-224.02068"
+ y="274.53128"
+ rx="15" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#rect5273"
+ id="use5335"
+ transform="translate(318.97597,268.31614)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#rect5273-22"
+ id="use5355"
+ transform="translate(318.97592,-176.5)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#rect5273-7"
+ id="use5359"
+ transform="translate(318.97597,32.954225)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#use5359"
+ id="use5361"
+ transform="translate(1.630859e-6,86.769591)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#use5335"
+ id="use5363"
+ transform="translate(0,173.33215)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#use5361"
+ id="use5365"
+ transform="translate(0,173.66424)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <text
+ xml:space="preserve"
+ style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="-58.692513"
+ y="114.39204"
+ id="text5371"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan5373"
+ x="-58.692513"
+ y="114.39204">some text</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="146.77734"
+ y="147.73293"
+ id="text5371-7"
+ sodipodi:linespacing="125%"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643"><tspan
+ sodipodi:role="line"
+ id="tspan5373-3"
+ x="146.77734"
+ y="147.73293">acceptor</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="146.53125"
+ y="233.42836"
+ id="text5371-74"
+ sodipodi:linespacing="125%"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643"><tspan
+ sodipodi:role="line"
+ id="tspan5373-5"
+ x="146.53125"
+ y="233.42836">parser</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="146.53125"
+ y="407.78009"
+ id="text5371-5"
+ sodipodi:linespacing="125%"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643"><tspan
+ sodipodi:role="line"
+ id="tspan5373-0"
+ x="146.53125"
+ y="407.78009">router</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="-58.692513"
+ y="53.112247"
+ id="text5371-2"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan5373-6"
+ x="-58.692513"
+ y="53.112247">some text</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="147.00391"
+ y="321.39722"
+ id="text5371-2-3"
+ sodipodi:linespacing="125%"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643"><tspan
+ sodipodi:role="line"
+ id="tspan5373-6-7"
+ x="147.00391"
+ y="321.39722">onrequest</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="146.53125"
+ y="495.07318"
+ id="text5371-2-3-0"
+ sodipodi:linespacing="125%"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643"><tspan
+ sodipodi:role="line"
+ id="tspan5373-6-7-3"
+ x="146.53125"
+ y="495.07318">handler</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="-446.99591"
+ y="63.078125"
+ id="text5371-2-3-0-7"
+ sodipodi:linespacing="125%"
+ transform="matrix(0,-1,1,0,0,0)"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643"><tspan
+ sodipodi:role="line"
+ id="tspan5373-6-7-3-9"
+ x="-446.99591"
+ y="63.078125">middlewares</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="-58.692513"
+ y="236.95154"
+ id="text5371-4"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan5373-9"
+ x="-58.692513"
+ y="236.95154">some text</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="147.00391"
+ y="60.912468"
+ id="text5371-4-0"
+ sodipodi:linespacing="125%"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643"><tspan
+ sodipodi:role="line"
+ id="tspan5373-9-2"
+ x="147.00391"
+ y="60.912468">client</tspan></text>
+ <use
+ x="0"
+ y="0"
+ xlink:href="#rect5273-7"
+ id="use5668"
+ transform="translate(589.05532,207.03588)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#rect5273"
+ id="use5670"
+ transform="translate(589.05538,355.27934)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#use5355"
+ id="use5672"
+ transform="translate(270.07946,434.91762)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <use
+ x="0"
+ y="0"
+ xlink:href="#text5371-4-0"
+ id="use5674"
+ transform="translate(270.29655,434.16115)"
+ width="744.09448"
+ height="1052.3622"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643" />
+ <text
+ xml:space="preserve"
+ style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="417.30829"
+ y="321.42792"
+ id="text5371-9"
+ sodipodi:linespacing="125%"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643"><tspan
+ sodipodi:role="line"
+ id="tspan5373-57"
+ x="417.30829"
+ y="321.42792">reply</tspan></text>
+ <text
+ xml:space="preserve"
+ style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+ x="417.30829"
+ y="407.77994"
+ id="text5371-2-0"
+ sodipodi:linespacing="125%"
+ inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+ inkscape:export-xdpi="89.926643"
+ inkscape:export-ydpi="89.926643"><tspan
+ sodipodi:role="line"
+ id="tspan5373-6-8"
+ x="417.30829"
+ y="407.77994">onresponse</tspan></text>
+ </g>
+</svg>
diff --git a/guide/toc.md b/guide/toc.md
index f30a5bd..6543ca1 100644
--- a/guide/toc.md
+++ b/guide/toc.md
@@ -8,89 +8,83 @@ Introducing Cowboy
------------------
* [Introduction](introduction.md)
- * Purpose
- * Prerequisites
- * Supported platforms
- * Conventions
* [The modern Web](modern_web.md)
- * The prehistoric Web
- * HTTP/1.1
- * REST
- * Long-polling
- * HTML5
- * EventSource
- * Websocket
- * SPDY
- * HTTP/2.0
* [Erlang and the Web](erlang_web.md)
- * The Web is concurrent
- * The Web is soft real time
- * The Web is asynchronous
- * The Web is omnipresent
- * Erlang is the ideal platform for the Web
* [Erlang for beginners](erlang_beginners.md)
* [Getting started](getting_started.md)
-Using Cowboy
-------------
+HTTP
+----
+ * [The life of a request](http_req_life.md)
+<!-- you are here -->
* [Routing](routing.md)
- * Purpose
- * Structure
- * Match syntax
- * Constraints
- * Compilation
- * Live update
- * [Handlers](handlers.md)
- * Purpose
- * Protocol upgrades
- * Custom protocol upgrades
- * [HTTP handlers](http_handlers.md)
- * Purpose
- * Usage
- * [Loop handlers](loop_handlers.md)
- * Purpose
- * Usage
- * [Websocket handlers](ws_handlers.md)
- * Purpose
- * Usage
- * [REST handlers](rest_handlers.md)
- * Purpose
- * Usage
- * Flow diagram
- * Methods
- * Callbacks
- * Meta data
- * Response headers
+ * [Handling plain HTTP requests](http_handlers.md)
+ * [The Req object](req.md)
+ * Reading the request body
+ * Sending a response
+
+Static files
+------------
+
* [Static handlers](static_handlers.md)
- * Purpose
- * Usage
- * MIME type
- * [Request object](req.md)
- * Purpose
- * Request
- * Request body
- * Multipart request body
- * Response
- * Chunked response
- * Response preconfiguration
- * Closing the connection
- * Reducing the memory footprint
+ * Distributed CDN solutions
+
+REST
+----
+
+ * REST principles
+ * Media types explained
+ * HTTP caching
+ * [Handling REST requests](rest_handlers.md)
+ * HEAD/GET requests flowchart
+ * POST/PUT/PATCH requests flowchart
+ * DELETE requests flowchart
+ * OPTIONS requests flowchart
+ * Designing a REST API
+
+Multipart
+---------
+
+ * Understanding multipart
+ * Multipart requests
+ * Multipart responses
+
+Server push technologies
+------------------------
+
+ * Push technologies
+ * [Using loop handlers for server push](loop_handlers.md)
+ * CORS
+
+Using Websocket
+---------------
+
+ * The Websocket protocol
+ * [Handling Websocket connections](ws_handlers.md)
+
+Advanced HTTP
+-------------
+
+ * Authentication
+ * Sessions
+
+Advanced Cowboy usage
+---------------------
+
+ * Optimization guide
* [Hooks](hooks.md)
- * On request
- * On response
* [Middlewares](middlewares.md)
- * Purpose
- * Usage
- * Configuration
- * Routing middleware
- * Handler middleware
+ * Access and error logs
+ * Handling broken clients
+ * HTTP header names
+ * HTTP/1.1 streaming not chunked
+
+Old guide misc
+--------------
+
+This section will be removed as content is moved into other chapters.
+
+ * [Handlers](handlers.md)
* [Internals](internals.md)
- * Architecture
- * One process for many requests
- * Lowercase header names
- * Improving performance
* [Resources](resources.md)
- * Frameworks
- * Helper libraries
- * Articles