Adding upstream version 2.6.12.upstream/2.6.12upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 96 insertions, 0 deletions

diff --git a/doc/internals/entities.txt b/doc/internals/entities.txt
new file mode 100644
index 0000000..cdde82e
--- /dev/null
+++ b/doc/internals/entities.txt
@@ -0,0 +1,96 @@
+2011/02/25 - Description of the different entities in haproxy - w@1wt.eu
+
+
+1) Definitions
+--------------
+
+Listener
+--------
+
+A listener is the entity which is part of a frontend and which accepts
+connections. There are as many listeners as there are ip:port couples.
+There is at least one listener instantiated for each "bind" entry, and
+port ranges will lead to as many listeners as there are ports in the
+range. A listener just has a listening file descriptor ready to accept
+incoming connections and to dispatch them to upper layers.
+
+
+Initiator
+---------
+
+An initiator is instantiated for each incoming connection on a listener. It may
+also be instantiated by a task pretending to be a client. An initiator calls
+the next stage's accept() callback to present it with the parameters of the
+incoming connection.
+
+
+Session
+-------
+
+A session is the only entity located between an initiator and a connector.
+This is the last stage which offers an accept() callback, and all of its
+processing will continue with the next stage's connect() callback. It holds
+the buffers needed to forward the protocol data between each side. This entity
+sees the native protocol, and is able to call analysers on these buffers. As it
+is used in both directions, it always has two buffers.
+
+When transformations are required, some of them may be done on the initiator
+side and other ones on the connector side. If additional buffers are needed for
+such transforms, those buffers cannot replace the session's buffers, but they
+may complete them.
+
+A session only needs to be instantiated when forwarding of data is required
+between two sides. Accepting and filtering on layer 4 information only does not
+require a session.
+
+For instance, let's consider the case of a proxy which receives and decodes
+HTTPS traffic, processes it as HTTP and recodes it as HTTPS before forwarding
+it. We'd have 3 layers of buffers, where the middle ones are used for
+forwarding of the protocol data (HTTP here) :
+
+            <-- ssl dec --> <-forwarding-> <-- ssl enc -->
+
+              ,->[||||]--.   ,->[||||]--.   ,->[||||]--.
+   client  (|)            (|)            (|)            (|)  server
+              ^--[||||]<-'   ^--[||||]<-'   ^--[||||]<-'
+
+                  HTTPS          HTTP          HTTPS
+
+The session handling code is only responsible for monitoring the forwarding
+buffers here. It may declare the end of the session once those buffers are
+closed and no analyser wants to re-open them. The session is also the entity
+which applies the load balancing algorithm and decides the server to use.
+
+The other sides are responsible for propagating the state up to the session
+which takes decisions.
+
+
+Connector
+---------
+
+A connector is the entity which permits to instantiate a connection to a known
+destination. It presents a connect() callback, and as such appears on the right
+side of diagrams.
+
+
+Connection
+----------
+
+A connection is the entity instantiated by a connector. It may be composed of
+multiple stages linked together. Generally it is the part of the stream
+interface holding a file descriptor, but it can also be a processing block or a
+transformation block terminated by a connection. A connection presents a
+server-side interface.
+
+
+2) Sequencing
+-------------
+
+Upon startup, listeners are instantiated by the configuration. When an incoming
+connection reaches a listening file descriptor, its read() callback calls the
+corresponding listener's accept() function which instantiates an initiator and
+in turn recursively calls upper layers' accept() callbacks until
+accept_session() is called. accept_session() instantiates a new session which
+starts protocol analysis via process_session(). When all protocol analysis is
+done, process_session() calls the connect() callback of the connector in order
+to get a connection.