1
0
Fork 0
mirror of https://github.com/warmcat/libwebsockets.git synced 2025-03-09 00:00:04 +01:00
libwebsockets/minimal-examples
Andy Green dcaa0013b4 lecp: add CBOR stream parser LECP like JSON LEJP
This provides very memory-efficient CBOR stream parsing
and writing.

The parser  converts pieces of CBOR into callbacks that define
the structure and collate string and blobs into buffer chunks
for extensible and easy access.

It is fragementation-safe and does not need all the CBOR in
the same place at one time, chunks of CBOR are parsed and
discarded as provided.

It does not allocate and just needs a few hundred bytes of
stack for even huge CBOR objects.  Huge strings and blobs
are handled without needing memory to hold them atomically.

Includes ./minimal-examples/api-tests/api-test-lecp that
unit tests it against 82 official example CBORs and
26 additional test vectors from COSE (just checking the CBOR
parsing).

The writing apis allow printf style semantics with a variety
of CBOR-aware %-formats.  The apis write into a context that
manages output buffer usage, if the output buffer fills,
then the apis return with an AGAIN code that lets you issue
and reset the output buffer and repeat the api all to issue
more output.  The subsequent calls can occur much later or
from a different function context, so this is perfect for
WRITEABLE-mediated output from the network parts of lws.

See ./READMEs/README.cbor-lecp.md
2021-08-21 17:44:40 +01:00
..
abstract/protocols/smtp-client cmake: latest cmake shows dep warnings for scripts < 2.8.12 2020-12-06 19:44:54 +00:00
api-tests lecp: add CBOR stream parser LECP like JSON LEJP 2021-08-21 17:44:40 +01:00
client-server Wextra 2021-07-04 10:29:54 +01:00
crypto tls: mbedtls-3 2021-07-13 13:22:50 +01:00
dbus-client sai: xenial 2021-02-28 19:05:25 +00:00
dbus-server Wextra 2021-07-04 10:29:54 +01:00
embedded/esp32 cpd: pass up lws_ss_request_tx ret 2021-08-16 08:07:32 +01:00
gtk/minimal-gtk Wextra 2021-07-04 10:29:54 +01:00
http-client http: cookies: support cookie jar in and out 2021-08-21 17:44:40 +01:00
http-server minimal: eventlib-custom: handle fds removal in service 2021-08-19 05:31:15 +01:00
mqtt-client Wextra 2021-07-04 10:29:54 +01:00
raw Wextra 2021-07-04 10:29:54 +01:00
secure-streams minimal: perf: add --test404[red] switches 2021-08-19 10:02:16 +01:00
ws-client Wextra 2021-07-04 10:29:54 +01:00
ws-server Wextra 2021-07-04 10:29:54 +01:00
CMakeLists.txt cmakelist: Augean Stables refactor 2020-05-27 08:40:12 +01:00
README.md client: secure streams 2020-03-04 12:17:49 +00:00

name demonstrates
client-server Minimal examples providing client and server connections simultaneously
crypto Minimal examples related to using lws crypto apis
dbus-server Minimal examples showing how to integrate DBUS into lws event loop
http-client Minimal examples providing an http client
http-server Minimal examples providing an http server
raw Minimal examples related to adopting raw file or socket descriptors into the event loop
secure-streams Minimal examples related to the Secure Streams client api
ws-client Minimal examples providing a ws client
ws-server Minimal examples providing a ws server (and an http server)

FAQ

Getting started

Build and install lws itself first (note that after installing lws on *nix, you need to run ldconfig one time so the OS can learn about the new library. Lws installs in /usr/local by default, Debian / Ubuntu ldconfig knows to look there already, but Fedora / CentOS need you to add the line /usr/local/lib to /etc/ld.so.conf and run ldconfig)

Then start with the simplest:

http-server/minimal-http-server

Why are most of the sources split into a main C file file and a protocol file?

Lws supports three ways to implement the protocol callback code:

  • you can just add it all in the same source file

  • you can separate it as these examples do, and #include it into the main sources

  • you can build it as a standalone plugin that is discovered and loaded at runtime.

The way these examples are structured, you can easily also build the protocol callback as a plugin just with a different CMakeLists.txt... see https://github.com/warmcat/libwebsockets/tree/master/plugin-standalone for an example.

Why would we want the protocol as a plugin?

You will notice a lot of the main C code is the same boilerplate repeated for each example. The actual interesting part is in the protocol callback only.

Lws provides (-DLWS_WITH_LWSWS=1) a generic lightweight server app called 'lwsws' that can be configured by JSON. Combined with your protocol as a plugin, it means you don't actually have to make a special server "app" part, you can just use lwsws and pass per-vhost configuration from JSON into your protocol. (Of course in some cases you have an existing app you are bolting lws on to, then you don't care about this for that particular case).

Because lwsws has no dependency on whatever your plugin does, it can mix and match different protocols randomly without needing any code changes. It reduces the size of the task to just writing the code you care about in your protocol handler, and nothing else to write or maintain.

Lwsws supports advanced features like reload, where it starts a new server instance with changed config or different plugins, while keeping the old instance around until the last connection to it closes.

I get why there is a pss, but why is there a vhd?

The pss is instantiated per-connection. But there are almost always other variables that have a lifetime longer than a single connection.

You could make these variables "filescope" one-time globals, but that means your protocol cannot instantiate multiple times.

Lws supports vhosts (virtual hosts), for example both https://warmcat.com and https://libwebsockets are running on the same lwsws instance on the same server and same IP... each of these is a separate vhost.

Your protocol may be enabled on multiple vhosts, each of these vhosts provides a different vhd specific to the protocol instance on that vhost. For example many of the samples keep a linked-list head to a list of live pss in the vhd... that means it's cleanly a list of pss opened on that vhost. If another vhost has the protocol enabled, connections to that will point to a different vhd, and the linked-list head on that vhd will only list connections to his vhost.

The example "ws-server/minimal-ws-server-threads" demonstrates how to deliver external configuration data to a specific vhost + protocol combination using code. In lwsws, this is simply a matter of setting the desired JSON config.