coeurl/README.md

coeurl

Simple library to do http requests asynchronously via CURL in C++. (Eventually as coroutines, once all the compilers I need to support support them.)

This is based on the CURL-libevent example.

You can do a get request with 3 simple steps:

1. Initialize the library: cpp coeurl::Client g{};
2. Do a request cpp g.get("http://localhost:5000/", [](const coeurl::Request &res) { std::cout << res.response() << std::endl; });

If you need more flexibility, you can initialize a coeurl::Request manually and set all the fields required. Currently only a few methods are exposed, but we may decide to add more in the future or expose the easy handle for direct manipulation.

Dependencies

• CURL (duh!)
• libevent
• spdlog
• for tests: doctest

Building

Usually meson should do all you need. For example you can build it like this in a subdirectory called buildir/:

meson setup builddir
meson compile -C builddir

There is also a cmake file, but this does not properly support installation. It is only useful for using this project via ExternalProject.

Limitations

The event loop can only run on one thread at a time! If you need to parallelize your request, use multiple clients or dispatch the responses into a threadpool manually. In most cases the one thread should be enough for the simpler workloads though and this way you can benefit from connection pooling and the HTTP/2 multiplexing. The tread is created internally and you currently have no control over it. You can wait for it to exit using close() or the ~Client destructor. If you block this thread, no other requests will get processed.

This library also only exposes the simple way to do things currently. This is all I need at the moment.

Interesting bits

• You can enable logging or customize the logging by setting a logger with coeurl::Client::set_logger. Do this before you initialize any client!
• The Request can be constructed builder style, then submitted and then you can query the Request once it has completed for the headers, status code, etc.
• Don't modify the Request while it is in flight or call any members on it until it is completed, after you submitted it.