diff options
Diffstat (limited to 'docs/en/cowboy/2.0/guide/flow_diagram/index.html')
| -rw-r--r-- | docs/en/cowboy/2.0/guide/flow_diagram/index.html | 121 |
1 files changed, 19 insertions, 102 deletions
diff --git a/docs/en/cowboy/2.0/guide/flow_diagram/index.html b/docs/en/cowboy/2.0/guide/flow_diagram/index.html index 65fe9305..d518183a 100644 --- a/docs/en/cowboy/2.0/guide/flow_diagram/index.html +++ b/docs/en/cowboy/2.0/guide/flow_diagram/index.html @@ -62,113 +62,30 @@ <h1 class="lined-header"><span>Flow diagram</span></h1> -<div class="paragraph"><p>Cowboy is a lightweight HTTP server with support for HTTP/1.1, -HTTP/2 and Websocket.</p></div> -<div class="paragraph"><p>It is built on top of Ranch. Please see the Ranch guide for more -information about how the network connections are handled.</p></div> -<div class="sect1"> +<p>Cowboy is a lightweight HTTP server with support for HTTP/1.1, HTTP/2 and Websocket.</p> +<p>It is built on top of Ranch. Please see the Ranch guide for more information about how the network connections are handled.</p> <h2 id="_overview">Overview</h2> -<div class="sectionbody"> -<div class="imageblock"> -<div class="content"> -<img src="../http_req_resp.png" alt="HTTP request/response flowchart" /> -</div> -</div> -<div class="paragraph"><p>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.</p></div> -<div class="paragraph"><p>After Ranch accepts a new connection, whether it is an -HTTP/1.1 or HTTP/2 connection, Cowboy starts receiving -requests and handling them.</p></div> -<div class="paragraph"><p>In HTTP/1.1 all requests come sequentially. In HTTP/2 -the requests may arrive and be processed concurrently.</p></div> -<div class="paragraph"><p>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.</p></div> -<div class="paragraph"><p>By default Cowboy comes configured with a stream handler -called <code>cowboy_stream_h</code>. 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.</p></div> -<div class="paragraph"><p>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.</p></div> -</div> -</div> -<div class="sect1"> +<img src="../http_req_resp.png" alt="HTTP request/response flowchart"/><p>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.</p> +<p>After Ranch accepts a new connection, whether it is an HTTP/1.1 or HTTP/2 connection, Cowboy starts receiving requests and handling them.</p> +<p>In HTTP/1.1 all requests come sequentially. In HTTP/2 the requests may arrive and be processed concurrently.</p> +<p>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.</p> +<p>By default Cowboy comes configured with a stream handler called <code>cowboy_stream_h</code>. 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.</p> +<p>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.</p> <h2 id="_protocol_specific_headers">Protocol-specific headers</h2> -<div class="sectionbody"> -<div class="paragraph"><p>Cowboy takes care of protocol-specific headers and prevents -you from sending them manually. For HTTP/1.1 this includes -the <code>transfer-encoding</code> and <code>connection</code> headers. For HTTP/2 -this includes the colon headers like <code>:status</code>.</p></div> -<div class="paragraph"><p>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.</p></div> -</div> -</div> -<div class="sect1"> +<p>Cowboy takes care of protocol-specific headers and prevents you from sending them manually. For HTTP/1.1 this includes the <code>transfer-encoding</code> and <code>connection</code> headers. For HTTP/2 this includes the colon headers like <code>:status</code>.</p> +<p>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.</p> <h2 id="_number_of_processes_per_connection">Number of processes per connection</h2> -<div class="sectionbody"> -<div class="paragraph"><p>By default, Cowboy will use one process per connection, -plus one process per set of request/response (called a -stream, internally).</p></div> -<div class="paragraph"><p>The reason it creates a new process for every request is due -to the requirements of HTTP/2 where requests are executed -concurrently and independently from the connection. The -frames from the different requests end up interleaved on -the single TCP connection.</p></div> -<div class="paragraph"><p>The request processes are never reused. There is therefore -no need to perform any cleanup after the response has been -sent. The process will terminate and Erlang/OTP will reclaim -all memory at once.</p></div> -<div class="paragraph"><p>Cowboy ultimately does not require more than one process -per connection. It is possible to interact with the connection -directly from a stream handler, a low level interface to Cowboy. -They are executed from within the connection process, and can -handle the incoming requests and send responses. This is however -not recommended in normal circumstances, as a stream handler -taking too long to execute could have a negative impact on -concurrent requests or the state of the connection itself.</p></div> -</div> -</div> -<div class="sect1"> +<p>By default, Cowboy will use one process per connection, plus one process per set of request/response (called a stream, internally).</p> +<p>The reason it creates a new process for every request is due to the requirements of HTTP/2 where requests are executed concurrently and independently from the connection. The frames from the different requests end up interleaved on the single TCP connection.</p> +<p>The request processes are never reused. There is therefore no need to perform any cleanup after the response has been sent. The process will terminate and Erlang/OTP will reclaim all memory at once.</p> +<p>Cowboy ultimately does not require more than one process per connection. It is possible to interact with the connection directly from a stream handler, a low level interface to Cowboy. They are executed from within the connection process, and can handle the incoming requests and send responses. This is however not recommended in normal circumstances, as a stream handler taking too long to execute could have a negative impact on concurrent requests or the state of the connection itself.</p> <h2 id="_date_header">Date header</h2> -<div class="sectionbody"> -<div class="paragraph"><p>Because querying for the current date and time can be expensive, -Cowboy generates one <em>Date</em> header value every second, shares it -to all other processes, which then simply copy it in the response. -This allows compliance with HTTP/1.1 with no actual performance loss.</p></div> -</div> -</div> -<div class="sect1"> +<p>Because querying for the current date and time can be expensive, Cowboy generates one <em>Date</em> header value every second, shares it to all other processes, which then simply copy it in the response. This allows compliance with HTTP/1.1 with no actual performance loss.</p> <h2 id="_binaries">Binaries</h2> -<div class="sectionbody"> -<div class="paragraph"><p>Cowboy makes extensive use of binaries.</p></div> -<div class="paragraph"><p>Binaries are more efficient than lists for representing -strings because they take less memory space. Processing -performance can vary depending on the operation. Binaries -are known for generally getting a great boost if the code -is compiled natively. Please see the HiPE documentation -for more details.</p></div> -<div class="paragraph"><p>Binaries may end up being shared between processes. This -can lead to some large memory usage when one process keeps -the binary data around forever without freeing it. If you -see some weird memory usage in your application, this might -be the cause.</p></div> -</div> -</div> +<p>Cowboy makes extensive use of binaries.</p> +<p>Binaries are more efficient than lists for representing strings because they take less memory space. Processing performance can vary depending on the operation. Binaries are known for generally getting a great boost if the code is compiled natively. Please see the HiPE documentation for more details.</p> +<p>Binaries may end up being shared between processes. This can lead to some large memory usage when one process keeps the binary data around forever without freeing it. If you see some weird memory usage in your application, this might be the cause.</p> + |