Update the flowchart chapter

doc/src/guide/book.asciidoc

@@ -80,13 +80,3 @@ include::migrating_from_1.0.asciidoc[Migrating from Cowboy 1.0 to 2.0]
 // @todo Maybe history? Could take info from architecture also.
 
 include::specs.asciidoc[HTTP and other specifications]
-
-= 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::overview.asciidoc[Overview]

doc/src/guide/flow_diagram.asciidoc

@@ -9,9 +9,54 @@ information about how the network connections are handled.
 
 === Overview
 
-Placeholder section.
-
-// @todo Make the diagram.
+image::http_req_resp.png[HTTP request/response flowchart]
+
+As you can see on the diagram, the client
+begins by connecting to the server. This step is handled
+by a Ranch acceptor, which is a process dedicated to
+accepting new connections.
+
+After Ranch accepts a new connection, whether it is an
+HTTP/1.1 or HTTP/2 connection, Cowboy starts receiving
+requests and handling them.
+
+In HTTP/1.1 all requests come sequentially. In HTTP/2
+the requests may arrive and be processed concurrently.
+
+When a request comes in, Cowboy creates a stream, which
+is a set of request/response and all the events associated
+with them. The protocol code in Cowboy defers the handling
+of these streams to stream handler modules. When you
+configure Cowboy you may define one or more module that
+will receive all events associated with a stream, including
+the request, response, bodies, Erlang messages and more.
+
+By default Cowboy comes configured with a stream handler
+called `cowboy_stream_h`. This stream handler will create
+a new process for every request coming in, and then
+communicate with this process to read the body or send
+a response back. The request process executes middlewares
+which, by default, including the router and then the
+execution of handlers. Like stream handlers, middlewares
+may also be customized.
+
+A response may be sent at almost any point in this
+diagram. If the response must be sent before the stream
+is initialized (because an error occurred early, for
+example) then stream handlers receive a special event
+indicating this error.
+
+=== Protocol-specific headers
+
+Cowboy takes care of protocol-specific headers and prevents
+you from sending them manually. For HTTP/1.1 this includes
+the `transfer-encoding` and `connection` headers. For HTTP/2
+this includes the colon headers like `:status`.
+
+Cowboy will also remove protocol-specific headers from
+requests before passing them to stream handlers. Cowboy
+tries to hide the implementation details of all protocols
+as well as possible.
 
 === Number of processes per connection
 

doc/src/guide/http_req_resp.svg

@@ -15,7 +15,7 @@
    height="1052.3622047"
    id="svg2"
    version="1.1"
-   inkscape:version="0.48.4 r9939"
+   inkscape:version="0.92.1 r"
    sodipodi:docname="http_req_resp.svg"
    inkscape:export-filename="/home/essen/Dropbox/Public/drawing.png"
    inkscape:export-xdpi="90"
@@ -65,15 +65,15 @@
      inkscape:pageopacity="1"
      inkscape:pageshadow="2"
      inkscape:zoom="1.4142136"
-     inkscape:cx="82.28271"
-     inkscape:cy="764.83183"
+     inkscape:cx="172.08527"
+     inkscape:cy="762.31079"
      inkscape:document-units="px"
      inkscape:current-layer="layer1"
      showgrid="false"
-     inkscape:window-width="2560"
-     inkscape:window-height="1402"
+     inkscape:window-width="1920"
+     inkscape:window-height="1043"
      inkscape:window-x="0"
-     inkscape:window-y="38"
+     inkscape:window-y="0"
      inkscape:window-maximized="1"
      inkscape:snap-global="true"
      showguides="true">
@@ -101,51 +101,117 @@
      inkscape:label="Layer 1"
      inkscape:groupmode="layer"
      id="layer1">
-    <path
-       inkscape:export-ydpi="89.926643"
-       inkscape:export-xdpi="89.926643"
-       inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
-       inkscape:connector-curvature="0"
-       id="use5779"
-       d="M 194.29441,340.67017 369.64493,238.3853"
-       style="fill:none;stroke:#6d8e41;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2, 4;stroke-dashoffset:0" />
-    <path
-       inkscape:export-ydpi="89.926643"
-       inkscape:export-xdpi="89.926643"
-       inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
-       inkscape:connector-curvature="0"
-       id="use5777"
-       d="m 178.49877,231.1517 203.00246,0.045"
-       style="fill:none;stroke:#6d8e41;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:1.99999999, 3.99999998;stroke-dashoffset:0" />
-    <use
-       x="0"
-       y="0"
-       xlink:href="#g5650"
-       id="use5753"
-       transform="translate(475.11201,-117.70525)"
-       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" />
+    <g
+       transform="translate(193.54707,-32.134105)"
+       id="g5650-5-0">
+      <path
+         inkscape:connector-curvature="0"
+         id="path5570-3-9"
+         d="m -57.78256,351.41962 v 52.3259"
+         style="opacity:0.8;fill:none;stroke:#6d8e41;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <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-5-3"
+         style="opacity:0.8;fill:#6d8e41;fill-opacity:1;fill-rule:nonzero;stroke:#6d8e41;stroke-width:0;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         sodipodi:type="star" />
+    </g>
+    <g
+       transform="rotate(180,50.658226,375.46461)"
+       id="g5650-6-6">
+      <path
+         inkscape:connector-curvature="0"
+         id="path5570-2-0"
+         d="m -57.78256,351.41962 v 52.3259"
+         style="opacity:0.8;fill:none;stroke:#6d8e41;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <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-9-6"
+         style="opacity:0.8;fill:#6d8e41;fill-opacity:1;fill-rule:nonzero;stroke:#6d8e41;stroke-width:0;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         sodipodi:type="star" />
+    </g>
+    <g
+       transform="translate(193.54707,-119.75468)"
+       id="g5650-5">
+      <path
+         inkscape:connector-curvature="0"
+         id="path5570-3"
+         d="m -57.78256,351.41962 v 52.3259"
+         style="opacity:0.8;fill:none;stroke:#6d8e41;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <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-5"
+         style="opacity:0.8;fill:#6d8e41;fill-opacity:1;fill-rule:nonzero;stroke:#6d8e41;stroke-width:0;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         sodipodi:type="star" />
+    </g>
+    <g
+       transform="rotate(180,50.658226,331.65432)"
+       id="g5650-6">
+      <path
+         inkscape:connector-curvature="0"
+         id="path5570-2"
+         d="m -57.78256,351.41962 v 52.3259"
+         style="opacity:0.8;fill:none;stroke:#6d8e41;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <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-9"
+         style="opacity:0.8;fill:#6d8e41;fill-opacity:1;fill-rule:nonzero;stroke:#6d8e41;stroke-width:0;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         sodipodi:type="star" />
+    </g>
     <rect
-       style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:2.44279909;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+       style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:2.44279909;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
        id="rect5367"
        width="207.05719"
        height="171.55719"
        x="43.721401"
-       y="276.1973"
+       y="384.1973"
        rx="11.072577"
        inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
        inkscape:export-xdpi="89.926643"
@@ -155,7 +221,7 @@
        y="0"
        xlink:href="#g5650"
        id="use5654"
-       transform="translate(205.03261,-31.336292)"
+       transform="translate(205.03261,76.66371)"
        width="744.09448"
        height="1052.3622"
        inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
@@ -223,17 +289,6 @@
          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"
@@ -274,247 +329,215 @@
        x="-224.02068"
        y="274.53128"
        rx="15" />
-    <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" />
-    <rect
-       rx="15"
-       y="386.37247"
-       x="94.955292"
-       height="36.392323"
-       width="104.5895"
-       id="use5363"
-       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" />
-    <use
-       x="0"
-       y="0"
-       xlink:href="#use5361"
-       id="use5365"
-       transform="translate(0,88.97624)"
-       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"
+       style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none"
        x="-58.692513"
        y="114.39204"
-       id="text5371"
-       sodipodi:linespacing="125%"><tspan
+       id="text5371"><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="323.0921"
-       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"
+         y="114.39204"
+         style="font-size:16px;line-height:1.25;font-family:sans-serif">some text</tspan></text>
+    <g
+       id="g3850">
+      <use
+         inkscape:export-ydpi="89.926643"
+         inkscape:export-xdpi="89.926643"
+         inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+         height="1052.3622"
+         width="744.09448"
+         transform="translate(318.97597,32.837526)"
+         id="use5359"
+         xlink:href="#rect5273-7"
+         y="0"
+         x="0" />
+      <a
+         id="a3826">
+        <text
+           xml:space="preserve"
+           style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none"
+           x="146.77739"
+           y="145.67879"
+           id="text5371-7"
+           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.77739"
+             y="145.67879"
+             style="font-size:16px;line-height:1.25;font-family:sans-serif">acceptor</tspan></text>
+      </a>
+    </g>
+    <g
+       id="g3860">
+      <use
+         inkscape:export-ydpi="89.926643"
+         inkscape:export-xdpi="89.926643"
+         inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+         height="1052.3622"
+         width="744.09448"
+         transform="translate(1.630859e-6,86.777953)"
+         id="use5361"
+         xlink:href="#use5359"
+         y="0"
+         x="0" />
+      <text
+         inkscape:export-ydpi="89.926643"
+         inkscape:export-xdpi="89.926643"
+         inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+         id="text5371-74"
+         y="232.91768"
+         x="147.26958"
+         style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none"
+         xml:space="preserve"><tspan
+           id="tspan3770"
+           style="font-size:16px;line-height:1.25;font-family:sans-serif"
+           y="232.91768"
+           x="147.26958"
+           sodipodi:role="line">protocol</tspan></text>
+    </g>
+    <g
+       id="g3904">
+      <use
+         inkscape:export-ydpi="89.926643"
+         inkscape:export-xdpi="89.926643"
+         inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+         height="1052.3622"
+         width="744.09448"
+         transform="translate(0,197.08458)"
+         id="use5365"
+         xlink:href="#use5361"
+         y="0"
+         x="0" />
+      <text
+         inkscape:export-ydpi="89.926643"
+         inkscape:export-xdpi="89.926643"
+         inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+         id="text5371-5"
+         y="431.0921"
          x="146.53125"
-         y="323.0921">router</tspan></text>
+         style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none"
+         xml:space="preserve"><tspan
+           style="font-size:16px;line-height:1.25;font-family:sans-serif"
+           y="431.0921"
+           x="146.53125"
+           id="tspan5373-0"
+           sodipodi:role="line">router</tspan></text>
+    </g>
     <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"
+       style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none"
        x="-58.692513"
        y="53.112247"
-       id="text5371-2"
-       sodipodi:linespacing="125%"><tspan
+       id="text5371-2"><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="146.53125"
-       y="410.38519"
-       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"
+         y="53.112247"
+         style="font-size:16px;line-height:1.25;font-family:sans-serif">some text</tspan></text>
+    <g
+       id="g3909">
+      <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-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         id="use5363"
+         width="104.5895"
+         height="36.392323"
+         x="94.955292"
+         y="494.37244"
+         rx="15" />
+      <text
+         inkscape:export-ydpi="89.926643"
+         inkscape:export-xdpi="89.926643"
+         inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+         id="text5371-2-3-0"
+         y="518.38519"
          x="146.53125"
-         y="410.38519">handler</tspan></text>
+         style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none"
+         xml:space="preserve"><tspan
+           style="font-size:16px;line-height:1.25;font-family:sans-serif"
+           y="518.38519"
+           x="146.53125"
+           id="tspan5373-6-7-3"
+           sodipodi:role="line">handler</tspan></text>
+    </g>
     <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="-362.30792"
+       style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none"
+       x="-470.30792"
        y="63.078125"
        id="text5371-2-3-0-7"
-       sodipodi:linespacing="125%"
-       transform="matrix(0,-1,1,0,0,0)"
+       transform="rotate(-90)"
        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="-362.30792"
-         y="63.078125">middlewares</tspan></text>
+         x="-470.30792"
+         y="63.078125"
+         style="font-size:16px;line-height:1.25;font-family:sans-serif">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"
+       style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none"
        x="-58.692513"
        y="236.95154"
-       id="text5371-4"
-       sodipodi:linespacing="125%"><tspan
+       id="text5371-4"><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"
+         y="236.95154"
+         style="font-size:16px;line-height:1.25;font-family:sans-serif">some text</tspan></text>
+    <g
+       id="g3855">
+      <use
+         inkscape:export-ydpi="89.926643"
+         inkscape:export-xdpi="89.926643"
+         inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+         height="1052.3622"
+         width="744.09448"
+         transform="translate(318.97592,-176.5)"
+         id="use5355"
+         xlink:href="#rect5273-22"
+         y="0"
+         x="0" />
+      <text
+         inkscape:export-ydpi="89.926643"
+         inkscape:export-xdpi="89.926643"
+         inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png"
+         id="text5371-4-0"
+         y="60.912468"
          x="147.00391"
-         y="60.912468">client</tspan></text>
-    <use
-       x="0"
-       y="0"
-       xlink:href="#rect5273-7"
-       id="use5668"
-       transform="translate(589.05532,122.34788)"
-       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,270.59134)"
-       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,350.22962)"
-       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,349.47315)"
-       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="236.73991"
-       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="236.73991">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="323.09195"
-       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="323.09195">onresponse</tspan></text>
+         style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none"
+         xml:space="preserve"><tspan
+           style="font-size:16px;line-height:1.25;font-family:sans-serif"
+           y="60.912468"
+           x="147.00391"
+           id="tspan5373-9-2"
+           sodipodi:role="line">client</tspan></text>
+    </g>
+    <g
+       id="g3865">
+      <rect
+         rx="15"
+         y="297.08545"
+         x="94.955299"
+         height="36.392323"
+         width="104.5895"
+         id="rect5273-3"
+         style="fill:#d1f2a5;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+      <text
+         id="text5371-2-6"
+         y="320.78552"
+         x="147.50005"
+         style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none"
+         xml:space="preserve"><tspan
+           style="font-size:16px;line-height:1.25;font-family:sans-serif"
+           y="320.78552"
+           x="147.50005"
+           id="tspan5373-6-7"
+           sodipodi:role="line">stream</tspan></text>
+    </g>
   </g>
 </svg>

doc/src/guide/overview.asciidoc

@@ -1,150 +0,0 @@
-[[overview]]
-== Request overview
-
-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:
-
-image::http_req_resp.png[HTTP request/response flowchart]
-
-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.
-
-HTTP/2 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.
-
-[source,erlang]
-----
-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.
-
-[source,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 (HTTP/2)
-
-In HTTP/2, 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.
-
-HTTP/2 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.