Libwebsockets: pure C library for http, websockets, MQTT

The documentation itself is actually good and extensive, however it feels like the authors expect its users to deeply understand the library itself. It is also harder to find some "Getting Started" docs as most provided examples felt way too bloated coming from a nodejs/ws background. Compared to the other library[1] I was considering, it took much longer to get even a simple "echo" server running.

However having used lws for some time now, I am really happy with it! The API is very clean, mostly intuitive and provides everything you need, without feeling bloated or becoming too verbose. Sometimes documentation still feels a bit harder to find, but it can be figured out eventually. One great feature for me was being able to accept both WebSocket as well as raw TCP connections on the same port, this is extremely easy and just required settings the flag LWS_SERVER_OPTION_FALLBACK_TO_RAW.

I encountered other hiccups. They are fully documented and completely valid, but were really confusing to me as a first-time user:

* Sending data requires a specific memory layout[2] – namely having to allocate memory for the websocket header youself before the actual message you want to send. This gave me confusing segfaults in the beginning.

* Sending data / responding to a client message will probably (but not always) fail when just naively using "lws_write()". To correctly send data you need to manually queue your message data, request the "ON_WRITABLE" callback[3] and only then actually send.

[1]: https://github.com/Theldus/wsServer

[2]: https://libwebsockets.org/lws-api-doc-v3.0-stable/html/group... (see the "IMPORTANT NOTICE")

[3]: https://libwebsockets.org/lws-api-doc-main/html/group__callb...

The majority of the things I list are optional features of the core library (rather than examples) enabled by cmake flags, some of which look to be enabled by default:

  option(LWS_WITH_JPEG "Enable stateful JPEG stream decoder" ON)

All these extra features may imply that it's grown past its original goals, and that the other bits and pieces could be split into smaller parts, etc.

There is no need for it. Rust already has libraries for http, websockets, and mqtt.

> This one has 13 years proven battlefield use. And by lord this myth of "Old therefore must be battle-tested" must die.

Case in appoint, I had to interact with a piece of software that used this library and it is as battle-tested as expecting HTTP headers in very specific casing!

Here is a comment from some code I wrote circa 2020 to deal with this issue. So it is not hypothetical.

    // libwebsocket/1.X.X is naive about http headers
    // and expects them in a specific case but node.js as
    // permitted by http spec doesn't care about case.
    // this patches node.js http to send headers as expected
    // by libwebsocket/VAA
    const { setHeader } = http.OutgoingMessage.prototype;
    http.OutgoingMessage.prototype.setHeader = function (name, value) {
      name = name
        .replace(/\b(\w)/g, (match, submatch) => (submatch ? submatch.toUpperCase() : ''))
        .replace(/(websocket|Websocket)/g, () => 'WebSocket');
    
      value = value.replace(/(websocket|Websocket)/g, () => 'WebSocket');
    
      setHeader.call(this, name, value);
    };

And because C is more popular in embedded, new vendors are more likely to pick it for new platforms instead of Rust, which doesn't help.