From 2368dc53d0c724f1899aeb2874ba1a763e11f0b8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Mon, 29 Jan 2024 15:40:26 +0100
Subject: Cowboy 2.11

---
 docs/en/cowboy/2.11/guide/flow_diagram.asciidoc | 109 ++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 docs/en/cowboy/2.11/guide/flow_diagram.asciidoc

(limited to 'docs/en/cowboy/2.11/guide/flow_diagram.asciidoc')

diff --git a/docs/en/cowboy/2.11/guide/flow_diagram.asciidoc b/docs/en/cowboy/2.11/guide/flow_diagram.asciidoc
new file mode 100644
index 00000000..9eb74667
--- /dev/null
+++ b/docs/en/cowboy/2.11/guide/flow_diagram.asciidoc
@@ -0,0 +1,109 @@
+[[flow_diagram]]
+== 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
+
+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.
+By default, the request process executes the router and then
+the 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.
-- 
cgit v1.2.3

