diff options
| -rw-r--r-- | doc/src/guide/book.asciidoc | 10 | ||||
| -rw-r--r-- | doc/src/guide/flow_diagram.asciidoc | 51 | ||||
| -rw-r--r-- | doc/src/guide/http_req_resp.png | bin | 28370 -> 20713 bytes | |||
| -rw-r--r-- | doc/src/guide/http_req_resp.svg | 557 | ||||
| -rw-r--r-- | doc/src/guide/overview.asciidoc | 150 |
5 files changed, 338 insertions, 430 deletions
diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc index 8178803..ed0f1c7 100644 --- a/doc/src/guide/book.asciidoc +++ b/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] diff --git a/doc/src/guide/flow_diagram.asciidoc b/doc/src/guide/flow_diagram.asciidoc index 4cb3bda..2d35d4d 100644 --- a/doc/src/guide/flow_diagram.asciidoc +++ b/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 diff --git a/doc/src/guide/http_req_resp.png b/doc/src/guide/http_req_resp.png Binary files differindex 8c9cae9..41c17c8 100644 --- a/doc/src/guide/http_req_resp.png +++ b/doc/src/guide/http_req_resp.png diff --git a/doc/src/guide/http_req_resp.svg b/doc/src/guide/http_req_resp.svg index d1e7f78..acedb15 100644 --- a/doc/src/guide/http_req_resp.svg +++ b/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> diff --git a/doc/src/guide/overview.asciidoc b/doc/src/guide/overview.asciidoc deleted file mode 100644 index 3e5cbb7..0000000 --- a/doc/src/guide/overview.asciidoc +++ /dev/null @@ -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. |
