DOC: internals: addd mworker V3 internals

Document the mworker V3 implementation introduced in HAProxy 3.1.
Explains the rationale behind moving configuration parsing out of the
master process to improve robustness.

Could be backported to 3.1.

diff --git a/doc/internals/mworker.md b/doc/internals/mworker.md
index bb51f622e9df968a5092783d5856cb438e12783e..f426336618d0ba61cc340b2d75ac0512c59fb015 100644 (file)
--- a/doc/internals/mworker.md
+++ b/doc/internals/mworker.md
@@ -208,3 +208,38 @@ starts with -st to achieve a hard stop on the previous worker.
 Version 3.0 got rid of the libsystemd dependencies for sd_notify() after the
 events of xz/openssh, the function is now implemented directly in haproxy in
 src/systemd.c.
+
+### mworker V3
+
+This version was implemented with HAProxy 3.1, the goal was to stop parsing and
+applying the configuration in the master process.
+
+One of the caveats of the previous implementation was that the parser could take
+a lot of time, and the master process would be stuck in the parser instead of
+handling its polling loop, signals etc. Some parts of the configuration parsing
+could also be less reliable with third-party code (EXTRA_OBJS), it could, for
+example, allow opening FDs and not closing them before the reload which
+would crash the master after a few reloads.
+
+The startup of the master-worker was reorganized this way:
+
+- the "discovery" mode, which is a lighter configuration parsing step, only
+  applies the configuration which need to be effective for the master process.
+  For example, "master-worker", "mworker-max-reloads" and less than 20 other
+  keywords that are identified by KWF_DISCOVERY in the code. It is really fast
+  as it don't need all the configuration to be applied in the master process.
+
+- the master will then fork a worker, with a PROC_O_INIT flag. This worker has
+  a temporary sockpair connected to the master CLI. Once the worker is forked,
+  the master initializes its configuration and starts its polling loop.
+
+- The newly forked worker will try to parse the configuration, which could
+  result in a failure (exit 1), or any bad error code. In case of success, the
+  worker will send a "READY" message to the master CLI then close this FD. At
+  this step everything was initialized and the worker can enter its polling
+  loop.
+
+- The master then waits for the worker, it could:
+   * receive the READY message over the mCLI, resulting in a successful loading
+     of haproxy
+   * receive a SIGCHLD, meaning the worker exited and couldn't load