haproxy
HAProxy Lua documentation is misleading (and incomplete)
https://www.haproxy.com/documentation/haproxy-lua-api/getting-started/introduction/
says:
HAProxy and HAProxy Enterprise have a non-blocking architecture and, because of that, Lua scripts must be written in a way that avoids reading files, making network calls, or performing other actions that might block the main thread of the load balancer process during runtime. The best place to read files and perform other blocking IO calls is within a core.register_init function. Then store that data in a global variable so that it can be accessed during runtime from a core.register_service block.
However, this blog post, in the Actions section: https://www.haproxy.com/blog/5-ways-to-extend-haproxy-with-lua#actions contradicts the documentation:
In contrast to converters and fetches, your Lua actions can and will often use socket functions, which allow them to communicate with external services. The Socket class is a replacement for the standard Lua Socket class and is compatible with HAProxy’s non-blocking nature. When you want to use socket functions in your actions, you must use this class.
(emphasis mine in both citations.)
So HAProxy not only allows doing "network calls" from its scripts, it actually provides specific tools (the Socket class) to do it in a non-blocking way, and the blog post encourages it and gives a specific example.
Other than that, it's a general problem that in order to understand how to actually extend HAProxy with Lua, I have to read a bunch of blog posts, there is no good official documentation provided. The "Common Lua tasks" section in the docs has one very simplistic example. The arpalert linked source looks a bit better, and it actually seems to provide a full API doc, but one person's personal website should probably not be considered an official source.
Even if the blog post https://www.haproxy.com/blog/5-ways-to-extend-haproxy-with-lua was just copied verbatim to the official docs, it would increase the value of these docs significantly.
https://www.arpalert.org/haproxy-api.html is the official lua documentation for HAProxy community edition which is maintained by the initial author of the Lua API in HAProxy.
These pages are generated from https://github.com/haproxy/haproxy/tree/master/doc/lua-api which contains the full API documentation.
This github project is only used for the community project, haproxy.com is not handled there.
We have plans to improve the Lua documentation. I'll incorporate your feedback. Thank you for this!
