Added a chapter about life of HTTP requests

Reworked the table of contents also.

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.

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>

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