MINOR: session: document explicitely that session_add_conn() is safe

A set of recent patches have simplified management of backend connection
attached to sessions. The API is now stricter to prevent any misuse.

One of this change is the addition of a BUG_ON() in session_add_conn(),
which ensures that a connection is not attached to a session if its
<owner> field points to another entry.

On older haproxy releases, this assertion could not be enforced due to
NTLM as a connection is turned as private during its transfer. When
using a true multiplexed protocol on the backend side, the connection
could be assigned in turn to several sessions. However, NTLM is now only
applied for HTTP/1.1 as it does not make sense if the connection is
already shared.

To better clarify this situation, extend the comment on BUG_ON() inside
session_add_conn().

diff --git a/include/haproxy/session.h b/include/haproxy/session.h
index 225041a337f8de5cd1ef4ca2fbaff539d5663620..714017ffa134e75674e4003a2366d0514143ea29 100644 (file)
--- a/include/haproxy/session.h
+++ b/include/haproxy/session.h
@@ -187,7 +187,15 @@ static inline int session_add_conn(struct session *sess, struct connection *conn
        /* Connection target is used to index it in the session. Only BE conns are expected in session list. */
        BUG_ON(!conn->target || objt_listener(conn->target));
 
-       /* A connection cannot be attached already to another session. */
+       /* A connection cannot be attached already to another session.
+        *
+        * This is safe as BE connections are flagged as private immediately
+        * after being created during connect_server(). The only potential
+        * issue would be if a connection is turned private later on during its
+        * lifetime. Currently, this happens only on NTLM headers detection,
+        * however this case is only implemented with HTTP/1.1 which cannot
+        * multiplex several streams on the same connection.
+        */
        BUG_ON(conn->owner && conn->owner != sess);
 
        /* Already attach to the session */