cpp httplib

cpp–httplib

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

It\’s extremely easy to set up. Just include the httplib.h file in your code!

Important

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)

#define CPPHTTPLIB_OPENSSL_SUPPORT
#include \"path/to/httplib.h\"

// HTTP
httplib::Server svr;

// HTTPS
httplib::SSLServer svr;

svr.Get(\"/hi\", [](const httplib::Request &, httplib::Response &res) {
  res.set_content(\"Hello World!\", \"text/plain\");
});

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

Client

#define CPPHTTPLIB_OPENSSL_SUPPORT
#include \"path/to/httplib.h\"

// HTTP
httplib::Client cli(\"http://yhirose.g*i*t*hub.io\");

// HTTPS
httplib::Client cli(\"https://yhirose.gi**t*hub.io\");

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 3.0 or later. Please see this page to get more information.

Tip

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

#define CPPHTTPLIB_OPENSSL_SUPPORT
#include \"path/to/httplib.h\"

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

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

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

// Disable cert verification
cli.enable_server_certificate_verification(false);

// Disable host verification
cli.enable_server_hostname_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.

SSL Error Handling

When SSL operations fail, cpp-httplib provides detailed error information through two separate error fields:

#define CPPHTTPLIB_OPENSSL_SUPPORT
#include \"path/to/httplib.h\"

httplib::Client cli(\"https://exam*p*le.*com\");

auto res = cli.Get(\"/\");
if (!res) {
  // Check the error type
  auto err = res.error();

  switch (err) {
    case httplib::Error::SSLConnection:
      std::cout << \"SSL connection failed, SSL error: \"
                << res->ssl_error() << std::endl;
      break;

    case httplib::Error::SSLLoadingCerts:
      std::cout << \"SSL cert loading failed, OpenSSL error: \"
                << std::hex << res->ssl_openssl_error() << std::endl;
      break;

    case httplib::Error::SSLServerVerification:
      std::cout << \"SSL verification failed, X509 error: \"
                << res->ssl_openssl_error() << std::endl;
      break;

    case httplib::Error::SSLServerHostnameVerification:
      std::cout << \"SSL hostname verification failed, X509 error: \"
                << res->ssl_openssl_error() << std::endl;
      break;

    default:
      std::cout << \"HTTP error: \" << httplib::to_string(err) << std::endl;
    }
  }
}

Server

#include <httplib.h>

int main(void)
{
  using namespace httplib;

  Server svr;

  svr.Get(\"/hi\", [](const Request& req, Response& res) {
    res.set_content(\"Hello World!\", \"text/plain\");
  });

  // Match the request path against a regular expression
  // and extract its captures
  svr.Get(R\"(/numbers/(\\d+))\", [&](const Request& req, Response& res) {
    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\", [&](const Request& req, Response& res) {
    auto user_id = req.path_params.at(\"id\");
    res.set_content(user_id, \"text/plain\");
  });

  // Extract values from HTTP headers and URL query params
  svr.Get(\"/body-header-param\", [](const Request& req, Response& res) {
    if (req.has_header(\"Content-Length\")) {
      auto val = req.get_header_value(\"Content-Length\");
    }
    if (req.has_param(\"key\")) {
      auto val = req.get_param_value(\"key\");
    }
    res.set_content(req.body, \"text/plain\");
  });

  // If the handler takes time to finish, you can also poll the connection state
  svr.Get(\"/task\", [&](const Request& req, Response& res) {
    const char * result = nullptr;
    process.run(); // for example, starting an external process
    while (result == nullptr) {
      sleep(1);
      if (req.is_connection_closed()) {
        process.kill(); // kill the process
        return;
      }
      result = process.stdout(); // != nullptr if the process finishes
    }
    res.set_content(result, \"text/plain\");
  });

  svr.Get(\"/stop\", [&](const Request& req, Response& res) {
    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

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

Static File Server

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

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

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

// Remove mount /
ret = svr.remove_mount_point(\"/\");

// Remove mount /public
ret = svr.remove_mount_point(\"/public\");

// 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 following are built-in mappings:

Warning

These static file server methods are not thread-safe.

File request handler

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

Logging

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

You can also set a pre-compression logger to capture request/response data before compression is applied. This is useful for debugging and monitoring purposes when you need to see the original, uncompressed response content:

svr.set_pre_compression_logger([](const auto& req, const auto& res) {
  // Log before compression - res.body contains uncompressed content
  // Content-Encoding header is not yet set
  your_pre_compression_logger(req, res);
});

The pre-compression logger is only called when compression would be applied. For responses without compression, only the regular logger is called.

Error handler

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.

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 = StatusCode::InternalServerError_500;
});

Caution

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

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

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

Pre request handler

svr.set_pre_request_handler([](const auto& req, auto& res) {
  if (req.matched_route == \"/user/:user\") {
    auto user = req.path_params.at(\"user\");
    if (user != \"john\") {
      res.status = StatusCode::Forbidden_403;
      res.set_content(\"error\", \"text/html\");
      return Server::HandlerResponse::Handled;
    }
  }
  return Server::HandlerResponse::Unhandled;
});

Form data handling

URL-encoded form data (\’application/x-www-form-urlencoded\’)

svr.Post(\"/form\", [&](const auto& req, auto& res) {
  // URL query parameters and form-encoded data are accessible via req.params
  std::string username = req.get_param_value(\"username\");
  std::string password = req.get_param_value(\"password\");

  // Handle multiple values with same name
  auto interests = req.get_param_values(\"interests\");

  // Check existence
  if (req.has_param(\"newsletter\")) {
    // Handle newsletter subscription
  }
});

\’multipart/form-data\’ POST data

svr.Post(\"/multipart\", [&](const Request& req, Response& res) {
  // Access text fields (from form inputs without files)
  std::string username = req.form.get_field(\"username\");
  std::string bio = req.form.get_field(\"bio\");

  // Access uploaded files
  if (req.form.has_file(\"avatar\")) {
    const auto& file = req.form.get_file(\"avatar\");
    std::cout << \"Uploaded file: \" << file.filename
              << \" (\" << file.content_type << \") - \"
              << file.content.size() << \" bytes\" << std::endl;

    // Access additional headers if needed
    for (const auto& header : file.headers) {
      std::cout << \"Header: \" << header.first << \" = \" << header.second << std::endl;
    }

    // Save to disk
    std::ofstream ofs(file.filename, std::ios::binary);
    ofs << file.content;
  }

  // Handle multiple values with same name
  auto tags = req.form.get_fields(\"tags\");  // e.g., multiple checkboxes
  for (const auto& tag : tags) {
    std::cout << \"Tag: \" << tag << std::endl;
  }

  auto documents = req.form.get_files(\"documents\");  // multiple file upload
  for (const auto& doc : documents) {
    std::cout << \"Document: \" << doc.filename
              << \" (\" << doc.content.size() << \" bytes)\" << std::endl;
  }

  // Check existence before accessing
  if (req.form.has_field(\"newsletter\")) {
    std::cout << \"Newsletter subscription: \" << req.form.get_field(\"newsletter\") << std::endl;
  }

  // Get counts for validation
  if (req.form.get_field_count(\"tags\") > 5) {
    res.status = StatusCode::BadRequest_400;
    res.set_content(\"Too many tags\", \"text/plain\");
    return;
  }

  // Summary
  std::cout << \"Received \" << req.form.fields.size() << \" text fields and \"
            << req.form.files.size() << \" files\" << std::endl;

  res.set_content(\"Upload successful\", \"text/plain\");
});

Receive content with a content receiver

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
      // This approach allows streaming processing of large files
      std::vector<FormData> items;
      content_reader(
        [&](const FormData &item) {
          items.push_back(item);
          return true;
        },
        [&](const char *data, size_t data_length) {
          items.back().content.append(data, data_length);
          return true;
        });

      // Process the received items
      for (const auto& item : items) {
        if (item.filename.empty()) {
          // Text field
          std::cout << \"Field: \" << item.name << \" = \" << item.content << std::endl;
        } else {
          // File
          std::cout << \"File: \" << item.name << \" (\" << item.filename << \") - \"
                    << item.content.size() << \" bytes\" << std::endl;
        }
      }
    } 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

const size_t DATA_CHUNK_SIZE = 4;

svr.Get(\"/stream\", [&](const Request &req, Response &res) {
  auto data = new std::string(\"abcdefg\");

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

Without content length:

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

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:

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;
    }
  );
});

Send file content

svr.Get(\"/content\", [&](const Request &req, Response &res) {
  res.set_file_content(\"./path/to/content.html\");
});

svr.Get(\"/content\", [&](const Request &req, Response &res) {
  res.set_file_content(\"./path/to/content\", \"text/html\");
});

\’Expect: 100-continue\’ handler

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

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

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

Keep-Alive connection

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

Timeout

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 max