cpp-httplib

A C++11 single-file header-only cross platform HTTP/HTTPS library.

It's extremely easy to setup. Just include the httplib.h file in your code!

NOTE: This library uses 'blocking' socket I/O. If you are looking for a library with 'non-blocking' socket I/O, this is not the one that you want.

Simple examples

Server (Multi-threaded)

```c++

define CPPHTTPLIBOPENSSLSUPPORT

include "path/to/httplib.h"

// HTTP httplib::Server svr;

// HTTPS httplib::SSLServer svr;

svr.Get("/hi", { res.set_content("Hello World!", "text/plain"); });

svr.listen("0.0.0.0", 8080); ```

Client

```c++

define CPPHTTPLIBOPENSSLSUPPORT

include "path/to/httplib.h"

// HTTP httplib::Client cli("http://cpp-httplib-server.yhirose.repl.co");

// HTTPS httplib::Client cli("https://cpp-httplib-server.yhirose.repl.co");

auto res = cli.Get("/hi"); res->status; res->body; ```

SSL Support

SSL support is available with CPPHTTPLIB_OPENSSL_SUPPORT. libssl and libcrypto should be linked.

NOTE: cpp-httplib currently supports only version 1.1.1 and 3.0.

NOTE for macOS: cpp-httplib now can use system certs with CPPHTTPLIB_USE_CERTS_FROM_MACOSX_KEYCHAIN. CoreFoundation and Security should be linked with -framework.

```c++

define CPPHTTPLIBOPENSSLSUPPORT

include "path/to/httplib.h"

// Server httplib::SSLServer svr("./cert.pem", "./key.pem");

// Client httplib::Client cli("https://localhost:1234"); // scheme + host httplib::SSLClient cli("localhost:1234"); // host httplib::SSLClient cli("localhost", 1234); // host, port

// Use your CA bundle cli.setcacert_path("./ca-bundle.crt");

// Disable cert verification cli.enableservercertificate_verification(false); ```

NOTE: When using SSL, it seems impossible to avoid SIGPIPE in all cases, since on some operating systems, SIGPIPE can only be suppressed on a per-message basis, but there is no way to make the OpenSSL library do so for its internal communications. If your program needs to avoid being terminated on SIGPIPE, the only fully general way might be to set up a signal handler for SIGPIPE to handle or ignore it yourself.

Server

```c++

include

int main(void) { using namespace httplib;

Server svr;

svr.Get("/hi", { res.set_content("Hello World!", "text/plain"); });

// Match the request path against a regular expression // and extract its captures svr.Get(R"(/numbers/(\d+))", & { auto numbers = req.matches[1]; res.set_content(numbers, "text/plain"); });

// Capture the second segment of the request path as "id" path param svr.Get("/users/:id", & { auto userid = req.pathparams.at("id"); res.setcontent(userid, "text/plain"); });

// Extract values from HTTP headers and URL query params svr.Get("/body-header-param", { if (req.hasheader("Content-Length")) { auto val = req.getheadervalue("Content-Length"); } if (req.hasparam("key")) { auto val = req.getparamvalue("key"); } res.set_content(req.body, "text/plain"); });

svr.Get("/stop", & { svr.stop(); });

svr.listen("localhost", 1234); } ```

Post, Put, Delete and Options methods are also supported.

Bind a socket to multiple interfaces and any available port

cpp int port = svr.bind_to_any_port("0.0.0.0"); svr.listen_after_bind();

Static File Server

```cpp // Mount / to ./www directory auto ret = svr.setmountpoint("/", "./www"); if (!ret) { // The specified base directory doesn't exist... }

// Mount /public to ./www directory ret = svr.setmountpoint("/public", "./www");

// Mount /public to ./www1 and ./www2 directories ret = svr.setmountpoint("/public", "./www1"); // 1st order to search ret = svr.setmountpoint("/public", "./www2"); // 2nd order to search

// Remove mount / ret = svr.removemountpoint("/");

// Remove mount /public ret = svr.removemountpoint("/public"); ```

cpp // User defined file extension and MIME type mappings svr.set_file_extension_and_mimetype_mapping("cc", "text/x-c"); svr.set_file_extension_and_mimetype_mapping("cpp", "text/x-c"); svr.set_file_extension_and_mimetype_mapping("hh", "text/x-h");

The followings are built-in mappings:

| Extension | MIME Type | Extension | MIME Type | | :--------- | :-------------------------- | :--------- | :-------------------------- | | css | text/css | mpga | audio/mpeg | | csv | text/csv | weba | audio/webm | | txt | text/plain | wav | audio/wave | | vtt | text/vtt | otf | font/otf | | html, htm | text/html | ttf | font/ttf | | apng | image/apng | woff | font/woff | | avif | image/avif | woff2 | font/woff2 | | bmp | image/bmp | 7z | application/x-7z-compressed | | gif | image/gif | atom | application/atom+xml | | png | image/png | pdf | application/pdf | | svg | image/svg+xml | mjs, js | application/javascript | | webp | image/webp | json | application/json | | ico | image/x-icon | rss | application/rss+xml | | tif | image/tiff | tar | application/x-tar | | tiff | image/tiff | xhtml, xht | application/xhtml+xml | | jpeg, jpg | image/jpeg | xslt | application/xslt+xml | | mp4 | video/mp4 | xml | application/xml | | mpeg | video/mpeg | gz | application/gzip | | webm | video/webm | zip | application/zip | | mp3 | audio/mp3 | wasm | application/wasm |

NOTE: These static file server methods are not thread-safe.

File request handler

cpp // The handler is called right before the response is sent to a client svr.set_file_request_handler([](const Request &req, Response &res) { ... });

Logging

cpp svr.set_logger([](const auto& req, const auto& res) { your_logger(req, res); });

Error handler

cpp svr.set_error_handler([](const auto& req, auto& res) { auto fmt = "<p>Error Status: <span style='color:red;'>%d</span></p>"; char buf[BUFSIZ]; snprintf(buf, sizeof(buf), fmt, res.status); res.set_content(buf, "text/html"); });

Exception handler

The exception handler gets called if a user routing handler throws an error.

cpp svr.set_exception_handler([](const auto& req, auto& res, std::exception_ptr ep) { auto fmt = "<h1>Error 500</h1><p>%s</p>"; char buf[BUFSIZ]; try { std::rethrow_exception(ep); } catch (std::exception &e) { snprintf(buf, sizeof(buf), fmt, e.what()); } catch (...) { // See the following NOTE snprintf(buf, sizeof(buf), fmt, "Unknown Exception"); } res.set_content(buf, "text/html"); res.status = 500; });

NOTE: if you don't provide the catch (...) block for a rethrown exception pointer, an uncaught exception will end up causing the server crash. Be careful!

Pre routing handler

cpp svr.set_pre_routing_handler([](const auto& req, auto& res) { if (req.path == "/hello") { res.set_content("world", "text/html"); return Server::HandlerResponse::Handled; } return Server::HandlerResponse::Unhandled; });

Post routing handler

cpp svr.set_post_routing_handler([](const auto& req, auto& res) { res.set_header("ADDITIONAL_HEADER", "value"); });

'multipart/form-data' POST data

cpp svr.Post("/multipart", [&](const auto& req, auto& res) { auto size = req.files.size(); auto ret = req.has_file("name1"); const auto& file = req.get_file_value("name1"); // file.filename; // file.content_type; // file.content; });

Receive content with a content receiver

cpp svr.Post("/content_receiver", [&](const Request &req, Response &res, const ContentReader &content_reader) { if (req.is_multipart_form_data()) { // NOTE: `content_reader` is blocking until every form data field is read MultipartFormDataItems files; content_reader( [&](const MultipartFormData &file) { files.push_back(file); return true; }, [&](const char *data, size_t data_length) { files.back().content.append(data, data_length); return true; }); } else { std::string body; content_reader([&](const char *data, size_t data_length) { body.append(data, data_length); return true; }); } });

Send content with the content provider

```cpp const sizet DATACHUNK_SIZE = 4;

svr.Get("/stream", & { auto data = new std::string("abcdefg");

res.setcontentprovider( data->size(), // Content length "text/plain", // Content type &, data { const auto &d = *data; sink.write(&d[offset], std::min(length, DATACHUNKSIZE)); return true; // return 'false' if you want to cancel the process. }, data { delete data; }); }); ```

Without content length:

cpp svr.Get("/stream", [&](const Request &req, Response &res) { res.set_content_provider( "text/plain", // Content type [&](size_t offset, DataSink &sink) { if (/* there is still data */) { std::vector<char> data; // prepare data... sink.write(data.data(), data.size()); } else { sink.done(); // No more data } return true; // return 'false' if you want to cancel the process. }); });

Chunked transfer encoding

cpp svr.Get("/chunked", [&](const Request& req, Response& res) { res.set_chunked_content_provider( "text/plain", [](size_t offset, DataSink &sink) { sink.write("123", 3); sink.write("345", 3); sink.write("789", 3); sink.done(); // No more data return true; // return 'false' if you want to cancel the process. } ); });

With trailer:

cpp svr.Get("/chunked", [&](const Request& req, Response& res) { res.set_header("Trailer", "Dummy1, Dummy2"); res.set_chunked_content_provider( "text/plain", [](size_t offset, DataSink &sink) { sink.write("123", 3); sink.write("345", 3); sink.write("789", 3); sink.done_with_trailer({ {"Dummy1", "DummyVal1"}, {"Dummy2", "DummyVal2"} }); return true; } ); });

'Expect: 100-continue' handler

By default, the server sends a 100 Continue response for an Expect: 100-continue header.

cpp // Send a '417 Expectation Failed' response. svr.set_expect_100_continue_handler([](const Request &req, Response &res) { return 417; });

cpp // Send a final status without reading the message body. svr.set_expect_100_continue_handler([](const Request &req, Response &res) { return res.status = 401; });

Keep-Alive connection

cpp svr.set_keep_alive_max_count(2); // Default is 5 svr.set_keep_alive_timeout(10); // Default is 5

Timeout

c++ svr.set_read_timeout(5, 0); // 5 seconds svr.set_write_timeout(5, 0); // 5 seconds svr.set_idle_interval(0, 100000); // 100 milliseconds

Set maximum payload length for reading a request body

c++ svr.set_payload_max_length(1024 * 1024 * 512); // 512MB

Server-Sent Events

Please see Server example and Client example.

Default thread pool support

ThreadPool is used as a default task queue, and the default thread count is 8, or std::thread::hardware_concurrency(). You can change it with CPPHTTPLIB_THREAD_POOL_COUNT.

If you want to set the thread count at runtime, there is no convenient way... But here is how.

cpp svr.new_task_queue = [] { return new ThreadPool(12); };

Override the default thread pool with yours

You can supply your own thread pool implementation according to your need.

```cpp class YourThreadPoolTaskQueue : public TaskQueue { public: YourThreadPoolTaskQueue(sizet n) { pool.startwiththread_count(n); }

virtual void enqueue(std::function fn) override { pool_.enqueue(fn); }

virtual void shutdown() override { pool.shutdowngracefully(); }

private: YourThreadPool pool_; };

svr.newtaskqueue = [] { return new YourThreadPoolTaskQueue(12); }; ```

Client

```c++

include

include

int main(void) { httplib::Client cli("localhost", 1234);

if (auto res = cli.Get("/hi")) { if (res->status == 200) { std::cout << res->body << std::endl; } } else { auto err = res.error(); std::cout << "HTTP error: " << httplib::to_string(err) << std::endl; } } ```

NOTE: Constructor with scheme-host-port string is now supported!

c++ httplib::Client cli("localhost"); httplib::Client cli("localhost:8080"); httplib::Client cli("http://localhost"); httplib::Client cli("http://localhost:8080"); httplib::Client cli("https://localhost"); httplib::SSLClient cli("localhost");

Error code

Here is the list of errors from Result::error().

c++ enum Error { Success = 0, Unknown, Connection, BindIPAddress, Read, Write, ExceedRedirectCount, Canceled, SSLConnection, SSLLoadingCerts, SSLServerVerification, UnsupportedMultipartBoundaryChars, Compression, ConnectionTimeout, };

GET with HTTP headers

c++ httplib::Headers headers = { { "Accept-Encoding", "gzip, deflate" } }; auto res = cli.Get("/hi", headers); or c++ auto res = cli.Get("/hi", {{"Accept-Encoding", "gzip, deflate"}}); or c++ cli.set_default_headers({ { "Accept-Encoding", "gzip, deflate" } }); auto res = cli.Get("/hi");

POST

c++ res = cli.Post("/post", "text", "text/plain"); res = cli.Post("/person", "name=john1&note=coder", "application/x-www-form-urlencoded");

POST with parameters

```c++ httplib::Params params; params.emplace("name", "john"); params.emplace("note", "coder");

auto res = cli.Post("/post", params); ``` or

```c++ httplib::Params params{ { "name", "john" }, { "note", "coder" } };

auto res = cli.Post("/post", params); ```

POST with Multipart Form Data

```c++ httplib::MultipartFormDataItems items = { { "text1", "text default", "", "" }, { "text2", "aωb", "", "" }, { "file1", "h\ne\n\nl\nl\no\n", "hello.txt", "text/plain" }, { "file2", "{\n \"world\", true\n}\n", "world.json", "application/json" }, { "file3", "", "", "application/octet-stream" }, };

auto res = cli.Post("/multipart", items); ```

PUT

c++ res = cli.Put("/resource/foo", "text", "text/plain");

DELETE

c++ res = cli.Delete("/resource/foo");

OPTIONS

c++ res = cli.Options("*"); res = cli.Options("/resource/foo");

Timeout

c++ cli.set_connection_timeout(0, 300000); // 300 milliseconds cli.set_read_timeout(5, 0); // 5 seconds cli.set_write_timeout(5, 0); // 5 seconds

Receive content with a content receiver

```c++ std::string body;

auto res = cli.Get("/large-data", & { body.append(data, data_length); return true; }); ```

```cpp std::string body;

auto res = cli.Get( "/stream", Headers(), & { EXPECTEQ(200, response.status); return true; // return 'false' if you want to cancel the request. }, & { body.append(data, datalength); return true; // return 'false' if you want to cancel the request. }); ```

Send content with a content provider

```cpp std::string body = ...;

auto res = cli.Post( "/stream", body.size(), { sink.write(body.data() + offset, length); return true; // return 'false' if you want to cancel the request. }, "text/plain"); ```

Chunked transfer encoding

cpp auto res = cli.Post( "/stream", [](size_t offset, DataSink &sink) { sink.os << "chunked data 1"; sink.os << "chunked data 2"; sink.os << "chunked data 3"; sink.done(); return true; // return 'false' if you want to cancel the request. }, "text/plain");

With Progress Callback

```cpp httplib::Client client(url, port);

// prints: 0 / 000 bytes => 50% complete auto res = cli.Get("/", { printf("%lld / %lld bytes => %d%% complete\n", len, total, (int)(len*100/total)); return true; // return 'false' if you want to cancel the request. } ); ```

Authentication

```cpp // Basic Authentication cli.setbasicauth("user", "pass");

// Digest Authentication cli.setdigestauth("user", "pass");

// Bearer Token Authentication cli.setbearertoken_auth("token"); ```

NOTE: OpenSSL is required for Digest Authentication.

Proxy server support

```cpp cli.set_proxy("host", port);

// Basic Authentication cli.setproxybasic_auth("user", "pass");

// Digest Authentication cli.setproxydigest_auth("user", "pass");

// Bearer Token Authentication cli.setproxybearertokenauth("pass"); ```

NOTE: OpenSSL is required for Digest Authentication.

Range

```cpp httplib::Client cli("httpbin.org");

auto res = cli.Get("/range/32", { httplib::makerangeheader({{1, 10}}) // 'Range: bytes=1-10' }); // res->status should be 206. // res->body should be "bcdefghijk". ```

cpp httplib::make_range_header({{1, 10}, {20, -1}}) // 'Range: bytes=1-10, 20-' httplib::make_range_header({{100, 199}, {500, 599}}) // 'Range: bytes=100-199, 500-599' httplib::make_range_header({{0, 0}, {-1, 1}}) // 'Range: bytes=0-0, -1'

Keep-Alive connection

```cpp httplib::Client cli("localhost", 1234);

cli.Get("/hello"); // with "Connection: close"

cli.setkeepalive(true); cli.Get("/world");

cli.setkeepalive(false); cli.Get("/last-request"); // with "Connection: close" ```

Redirect

```cpp httplib::Client cli("yahoo.com");

auto res = cli.Get("/"); res->status; // 301

cli.setfollowlocation(true); res = cli.Get("/"); res->status; // 200 ```

Use a specific network interface

NOTE: This feature is not available on Windows, yet.

cpp cli.set_interface("eth0"); // Interface name, IP address or host name

Compression

The server can apply compression to the following MIME type contents:

• all text types except text/event-stream
• image/svg+xml
• application/javascript
• application/json
• application/xml
• application/xhtml+xml

Zlib Support

'gzip' compression is available with CPPHTTPLIB_ZLIB_SUPPORT. libz should be linked.

Brotli Support

Brotli compression is available with CPPHTTPLIB_BROTLI_SUPPORT. Necessary libraries should be linked. Please see https://github.com/google/brotli for more detail.

Compress request body on client

c++ cli.set_compress(true); res = cli.Post("/resource/foo", "...", "text/plain");

Compress response body on client

c++ cli.set_decompress(false); res = cli.Get("/resource/foo", {{"Accept-Encoding", "gzip, deflate, br"}}); res->body; // Compressed data

Use poll instead of select

select system call is used as default since it's more widely supported. If you want to let cpp-httplib use poll instead, you can do so with CPPHTTPLIB_USE_POLL.

Split httplib.h into .h and .cc

```console $ ./split.py -h usage: split.py [-h] [-e EXTENSION] [-o OUT]

This script splits httplib.h into .h and .cc parts.

optional arguments: -h, --help show this help message and exit -e EXTENSION, --extension EXTENSION extension of the implementation file (default: cc) -o OUT, --out OUT where to write the files (default: out)

$ ./split.py Wrote out/httplib.h and out/httplib.cc ```

NOTE

g++

g++ 4.8 and below cannot build this library since <regex> in the versions are broken.

Windows

Include httplib.h before Windows.h or include Windows.h by defining WIN32_LEAN_AND_MEAN beforehand.

```cpp

include

include

```

```cpp

define WIN32LEANAND_MEAN

include

include

```

NOTE: cpp-httplib officially supports only the latest Visual Studio. It might work with former versions of Visual Studio, but I can no longer verify it. Pull requests are always welcome for the older versions of Visual Studio unless they break the C++11 conformance.

NOTE: Windows 8 or lower, Visual Studio 2013 or lower, and Cygwin on Windows are not supported.

License

MIT license (© 2023 Yuji Hirose)

Special Thanks To

These folks made great contributions to polish this library to totally another level from a simple toy!