curlws
curlws provides a cURL based websocket implementation.
Summary
cURL is a leading networking library and tool for the c world, but it lacks
websocket support. curlws provides a complementary library that uses
libcurl for the initial handshakes and underlying socket handling. Using libcurl
as the foundation provides an extremely robust, tested and powerful framework
for curlws.
Getting started
The best place to start is the cli
in the examples/cli/ directory. While a very simple application it shows the
power of this little library.
You can find the api here: https://github.com/xmidt-org/curlws/blob/main/include/curlws/curlws.h
Design Patterns
Single threaded by design
curlws is not designed to handle a multi-threaded environment. It certainly
can be used in one, but you will need to wrap it with the right threading magic
based on your choices and needs.
Sane defaults, default secure
Provide sane defaults. All you need to get started is a URL and a zeroed out configuration structure. If there is a choice of secure or insecure, we choose security and let you degrade as you see fit.
Leverage cURL & it's design patterns
While not everything was brought over from cURL, the callbacks and how you drive
the event thread with the curl_multi_* code should be familiar to most folks.
That also means there is a way to configure the cURL easy object with whatever
parameters and commands you want that we don't have today.
Quality and security first
There is nothing worse than a library that almost works right, but just doesn't.
The authors of curlws strive to be spec compliant and do so in flying colors.
Building and Testing
Start the Autobahn test server (Only needed to test)
This requires docker.
./tools/autobahn.sh
Build the code
meson setup --warnlevel 3 --werror build
cd build
ninja all test coverage
firefox meson-logs/coveragereport/index.html
Meson Configuration Options
See: https://github.com/xmidt-org/curlws/blob/main/meson_options.txt
Testing
To validate you will need jq installed.
To produce coverage results you need lcov installed.
ninja all test autobahn_collect autoban_validate coverage
Look at the results
The local autobahn server reports results here: http://localhost:8080
The lcov local code/branch coverage results can be found at build/meson-logs/coveragereport/index.html
Code of Conduct
This project and everyone participating in it are governed by the XMiDT Code Of Conduct. By participating, you agree to this Code.
Contributing
Refer to CONTRIBUTING.md.