From b5d4cb91f80c833795a2d87050c3674bb7aecdc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 3 Oct 2017 13:39:41 +0200 Subject: Update Hugo, docs --- docs/en/cowboy/2.0/guide/flow_diagram/index.html | 219 ++++++++++++----------- 1 file changed, 111 insertions(+), 108 deletions(-) (limited to 'docs/en/cowboy/2.0/guide/flow_diagram/index.html') 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 72e78d28..679ee0b1 100644 --- a/docs/en/cowboy/2.0/guide/flow_diagram/index.html +++ b/docs/en/cowboy/2.0/guide/flow_diagram/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Flow diagram @@ -67,119 +67,122 @@

Flow diagram

-

Cowboy is a lightweight HTTP server with support for HTTP/1.1, -HTTP/2 and Websocket.

-

It is built on top of Ranch. Please see the Ranch guide for more -information about how the network connections are handled.

-
-

Overview

-
-
-
-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

-
-

By default, Cowboy will use one process per connection, -plus one process per set of request/response (called a -stream, internally).

-

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.

-

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.

-

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.

-
-
-
-

Date header

-
-

Because querying for the current date and time can be expensive, -Cowboy generates one Date 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.

-
-
-
-

Binaries

-
-

Cowboy makes extensive use of binaries.

-

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.

-

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.

-
-
+

Cowboy is a lightweight HTTP server with support for HTTP/1.1, +HTTP/2 and Websocket.

+

It is built on top of Ranch. Please see the Ranch guide for more +information about how the network connections are handled.

+
+

Overview

+
+
+
+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

+
+

By default, Cowboy will use one process per connection, +plus one process per set of request/response (called a +stream, internally).

+

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.

+

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.

+

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.

+
+
+
+

Date header

+
+

Because querying for the current date and time can be expensive, +Cowboy generates one Date 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.

+
+
+
+

Binaries

+
+

Cowboy makes extensive use of binaries.

+

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.

+

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.

+
+
+ + +