Getting Started

Libwebsockets (LWS) is a flexible, lightweight pure C library for implementing modern network protocols easily with a tiny footprint, using a nonblocking event loop.

LWS is Free Software available under LGPL2 + Static Linking Exception license.

LWS roles

LWS Core code handles generic socket lifecycle, tls, vhosts, service threads, timers etc. "Roles" are wire protocol implementations on top of that, isolated via an ops struct:

RoleClientServer
http/1.x
http/2
websockets
ws-over-h2
raw tcp / udp / file

LWS supports optional TLS for client or server (including client certs) on any role.

New roles can be added cleanly to lws.

TLS (SSL) support

LWS equally supports OpenSSL-based and mbedTLS tls backend libraries. OpenSSL is faster but requires more memory; for constrained devices, you can trade off speed for memory footprint by selecting mbedTLS as the TLS backend.

LWS provides generic apis to access hashing, RSA, X509 and tls library features independent of the tls backend.

LWS Protocols

User code interfaces to LWS roles by providing a "protocol", including callback for events the code is interested in customizing.

Event loop libraries

LWS defaults to using poll(), however libuv, libevent and libev event libraries are all supported. LWS may both provide an internal loop, or participate cleanly in an external, "foreign" loop. New event libs can be added cleanly to lws.

LWS user code does not have to be customized depending on the event loop in use. For example LWS provides a generic high-resolution timer for each connection to arrange for delayed callbacks, hiding the details of the exact implementation depending on the chosen event loop.

Plaforms

LWS is available for unix-style platforms like Linux and BSD (including Mac), and also for Windows and even ESP32.

CMake is used to configure the sources for the platform it finds itself building on, and cross-build is also supported.

Scalability

LWS uses a singlethreaded nonblocking event loop, but it also supports having n of these in n threads, spreading the connections between them by allocating them to the least busy service thread, providing scalability to hundreds of thousands of connections in a single instance.

QA

LWS uses both Travis (Linux/gcc and Mac/clang) and Appveyor (Windows) to build-test 33 different configurations using -Wall and -Werror and more optional diagnostics on gcc.

After successful build, 1500 tests are run against Autobahn, h2spec, h2load, and lws suites with specific goals like http parser security and robustness, for both OpenSSL and mbedTLS. Any problems break the CI build.

Support

Look through the minimal examples and the docs.
Then: Mailing List.