mirror of
https://github.com/warmcat/libwebsockets.git
synced 2025-03-23 00:00:06 +01:00
122 lines
5.9 KiB
Markdown
122 lines
5.9 KiB
Markdown
[](https://travis-ci.org/warmcat/libwebsockets) [](https://ci.appveyor.com/project/lws-team/libwebsockets) [](https://scan.coverity.com/projects/3576) [](https://bestpractices.coreinfrastructure.org/projects/2266) [](https://www.codacy.com/app/lws-team/libwebsockets?utm_source=github.com&utm_medium=referral&utm_content=warmcat/libwebsockets&utm_campaign=Badge_Grade)
|
|
|
|
# Libwebsockets
|
|
|
|
Libwebsockets is a simple-to-use, pure C library providing client and server
|
|
for **http/1**, **http/2**, **websockets** and other protocols in a security-minded,
|
|
lightweight, configurable, scalable and flexible way. It's easy to build and
|
|
cross-build via cmake and is suitable for tasks from embedded RTOS through mass
|
|
cloud serving.
|
|
|
|
[50 minimal examples](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples) for
|
|
various scenarios, CC0-licensed (public domain) for cut-and-paste, allow you to get started quickly.
|
|
|
|
|
|
|
|
News
|
|
----
|
|
|
|
## Async DNS support
|
|
|
|
Master now provides optional Asynchronous (ie, nonblocking) DNS resolving. Enable
|
|
with `-DLWS_WITH_ASYNC_DNS=1` at cmake. This provides a quite sophisticated
|
|
ipv4 + ipv6 capable resolver that autodetects the dns server on several platforms
|
|
and operates a UDP socket to its port 53 to produce and parse DNS packets
|
|
from the event loop. And of course, it's extremely compact.
|
|
|
|
It broadly follows the getaddrinfo style api, but instead of creating the results
|
|
on the heap for each caller, it caches a single result according to the TTL and
|
|
then provides refcounted const pointers to the cached result to callers. While
|
|
there are references on the cached result it can't be reaped.
|
|
|
|
See `READMEs/README.async-dns.md` for detailed information on how it works, along
|
|
with `api-tests/api-test-async-dns` minimal example.
|
|
|
|
## Detailed Latency
|
|
|
|
You can now opt to measure and store us-resolution statistics on effective
|
|
latencies for client operations, and easily spool them to a file in a
|
|
format suitable for gnuplot, or handle in your own callback. Enable
|
|
`-DLWS_WITH_DETAILED_LATENCY=1` in cmake to build it into lws.
|
|
|
|
If you are concerned about operation latency or potential blocking from
|
|
user code, or behaviour under load, or latency variability on specific
|
|
platforms, you can get real numbers on your platform using this.
|
|
|
|
Timings for all aspects of events on connections are recorded, including
|
|
the time needed for name resolution, setting up the connection, tls
|
|
negotiation on both client and server sides, and each read and write.
|
|
|
|
See `READMEs/README.detailed-latency.md` for how to use it.
|
|
|
|
## Client connection logic rewrite
|
|
|
|
Lws master now makes much better use of the DNS results for ipv4 and ipv6... it
|
|
will iterate through them automatically making the best use it can of what's
|
|
provided and attempting new connections for each potentially usable one in turn
|
|
before giving up on the whole client connection attempt.
|
|
|
|
If ipv6 is disabled at cmake it can only use A / ipv4 records, but if ipv6 is
|
|
enabled, it tries both; if only ipv6 is enabled it promotes ipv4 to
|
|
::ffff:1.2.3.4 IPv4-in-IPv6 addresses.
|
|
|
|
## New network helpers for ipv4 and ipv6
|
|
|
|
An internal union `lws_sockaddr46` that combines `struct sockaddr_in` and
|
|
`struct sockaddr_in6` is now public, and there are helpers that can parse (using
|
|
`lws_tokenize`) any valid numeric representation for ipv4 and ipv6 either
|
|
into byte arrays and lengths, or directly to and from `lws_sockaddr46`.
|
|
|
|
## h2 long poll support
|
|
|
|
Lws now supports the convention that half-closing an h2 http stream may make
|
|
the stream 'immortal', in terms of not being bound by normal timeouts. For
|
|
the client side, there's an api that can be applied to the client stream to
|
|
make it transition to this "read-only" long poll mode.
|
|
|
|
See `READMEs/README.h2-long-poll.md` for full details, including how to test
|
|
it with the minimal examples.
|
|
|
|
## h1 client parser improvements
|
|
|
|
H1 is not so simple to parse because the header length is not known until it
|
|
has been fully parsed. The next header, or http body may be directly coalesced
|
|
with the header as well. Lws has supported bulk h1 parsing from a buffer for a
|
|
long time, but on clientside due to interactions with http proxying it had
|
|
been stuck parsing the header bytewise out of the tls buffer. In master,
|
|
everything now bulk parses from a buffer and uses a buflist to pass leftovers
|
|
through the event loop cleanly.
|
|
|
|
## `lws_sul` time refactor
|
|
|
|
Just before v3.2 there was a big refactor about how lws handles time. It now
|
|
explicitly schedules anything that may happen in the future on a single, sorted
|
|
linked-list, at us resolution. When entering a poll wait (or returning to an
|
|
event lib loop) it checks the interval between now and the earliest event on the
|
|
list to figure out how long to wait if there are no network events. For the
|
|
event loop case, it sets a native event lib timer to enforce it.
|
|
|
|
See `READMEs/README.lws_sul.md` for more details and a handy api where you can
|
|
schedule your own arbitrary callbacks using this system.
|
|
|
|
## Master is now MIT-licensed
|
|
|
|
Libwebsockets master is now under the MIT license. See ./LICENSE.
|
|
|
|
## Support
|
|
|
|
This is the libwebsockets C library for lightweight websocket clients and
|
|
servers. For support, visit
|
|
|
|
https://libwebsockets.org
|
|
|
|
and consider joining the project mailing list at
|
|
|
|
https://libwebsockets.org/mailman/listinfo/libwebsockets
|
|
|
|
You can get the latest version of the library from git:
|
|
|
|
- https://libwebsockets.org/git
|
|
|
|
Doxygen API docs for master: https://libwebsockets.org/lws-api-doc-master/html/index.html
|
|
|