[DOC] added a short descriptive of the backend mechanism
diff --git a/doc/backends.txt b/doc/backends.txt
new file mode 100644
index 0000000..d2474ce
--- /dev/null
+++ b/doc/backends.txt
@@ -0,0 +1,125 @@
+There has been a lot of confusion during the development because of the
+backends and frontends.
+
+What we want :
+
+- being able to still use a listener as it has always been working
+
+- being able to write a rule stating that we will *change* the backend when we
+ match some pattern. Only one jump is allowed.
+
+- being able to write a "use_filters_from XXX" line stating that we will ignore
+ any filter in the current listener, and that those from XXX will be borrowed
+ instead. A warning would be welcome for options which will silently get
+ masked. This is used to factor configuration.
+
+- being able to write a "use_backend_from XXX" line stating that we will ignore
+ any server and timeout config in the current listener, and that those from
+ XXX will be borrowed instead. A warning would be welcome for options which
+ will silently get masked. This is used to factor configuration.
+
+
+
+Example :
+---------
+
+ | # frontend HTTP/80
+ | listen fe_http 1.1.1.1:80
+ | use_filters_from default_http
+ | use_backend_from appli1
+ |
+ | # frontend HTTPS/443
+ | listen fe_https 1.1.1.1:443
+ | use_filters_from default_https
+ | use_backend_from appli1
+ |
+ | # frontend HTTP/8080
+ | listen fe_http-dev 1.1.1.1:8080
+ | reqadd "X-proto: http"
+ | reqisetbe "^Host: www1" appli1
+ | reqisetbe "^Host: www2" appli2
+ | reqisetbe "^Host: www3" appli-dev
+ | use_backend_from appli1
+ |
+ |
+ | # filters default_http
+ | listen default_http
+ | reqadd "X-proto: http"
+ | reqisetbe "^Host: www1" appli1
+ | reqisetbe "^Host: www2" appli2
+ |
+ | # filters default_https
+ | listen default_https
+ | reqadd "X-proto: https"
+ | reqisetbe "^Host: www1" appli1
+ | reqisetbe "^Host: www2" appli2
+ |
+ |
+ | # backend appli1
+ | listen appli1
+ | reqidel "^X-appli1:.*"
+ | reqadd "Via: appli1"
+ | balance roundrobin
+ | cookie app1
+ | server srv1
+ | server srv2
+ |
+ | # backend appli2
+ | listen appli2
+ | reqidel "^X-appli2:.*"
+ | reqadd "Via: appli2"
+ | balance roundrobin
+ | cookie app2
+ | server srv1
+ | server srv2
+ |
+ | # backend appli-dev
+ | listen appli-dev
+ | reqadd "Via: appli-dev"
+ | use_backend_from appli2
+ |
+ |
+
+
+Now we clearly see multiple things :
+------------------------------------
+
+ - a frontend can EITHER have filters OR reference a use_filter
+
+ - a backend can EITHER have servers OR reference a use_backend
+
+ - we want the evaluation to cross TWO levels per request. When a request is
+ being processed, it keeps track of its "frontend" side (where it came
+ from), and of its "backend" side (where the server-side parameters have
+ been found).
+
+ - the use_{filters|backend} have nothing to do with how the request is
+ decomposed.
+
+
+Conclusion :
+------------
+
+ - a proxy is always its own frontend. It also has 2 parameters :
+ - "fi_prm" : pointer to the proxy holding the filters (itself by default)
+ - "be_prm" : pointer to the proxy holding the servers (itself by default)
+
+ - a request has a frontend (fe) and a backend (be). By default, the backend
+ is initialized to the frontend. Everything related to the client side is
+ accessed through ->fe. Everything related to the server side is accessed
+ through ->be.
+
+ - request filters are first called from ->fe then ->be. Since only the
+ filters can change ->be, it is possible to iterate the filters on ->be
+ only and stop when ->be does not change anymore.
+
+ - response filters are first called from ->be then ->fe IF (fe != be).
+
+
+When we parse the configuration, we immediately configure ->fi and ->be for
+all proxies.
+
+Upon session creation, s->fe and s->be are initialized to the proxy. Filters
+are executed via s->fe->fi_prm and s->be->fi_prm. Servers are found in
+s->be->be_prm.
+