From 0556fb027c44cf80d3f77fb9c3fac4c504d6720c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Sun, 23 Jul 2017 09:48:25 +0200 Subject: Update the flowchart chapter --- doc/src/guide/book.asciidoc | 10 - doc/src/guide/flow_diagram.asciidoc | 51 +++- doc/src/guide/http_req_resp.png | Bin 28370 -> 20713 bytes doc/src/guide/http_req_resp.svg | 557 +++++++++++++++++++----------------- doc/src/guide/overview.asciidoc | 150 ---------- 5 files changed, 338 insertions(+), 430 deletions(-) delete mode 100644 doc/src/guide/overview.asciidoc 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 index 8c9cae9..41c17c8 100644 Binary files a/doc/src/guide/http_req_resp.png and b/doc/src/guide/http_req_resp.png differ 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"> - - - - + + + + + + + + + + + + + + + + - - - - - - some text - acceptor - parser - some text + + + + acceptor + + + + + protocol + + + + router + 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">router + some text - some text + + + handler + 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">handler + middlewares + x="-470.30792" + y="63.078125" + style="font-size:16px;line-height:1.25;font-family:sans-serif">middlewares some text - some text + + + client - - - - - reply - onresponse + 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">client + + + + stream + 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. -- cgit v1.2.3