ded/cpp-httplib
1
0
Fork 0
mirror of https://github.com/yhirose/cpp-httplib.git synced 2026-04-11 19:28:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation Site on GitHub Pages (#2376)

Browse Source 
* Add initial documentations

* Update documentation for Basic Client and add WebSocket section

* feat: add a static site generator with multi-language support

- Introduced a new Rust-based static site generator in the `docs-gen` directory.
- Implemented core functionality for building sites from markdown files, including:
  - Configuration loading from `config.toml`.
  - Markdown rendering with frontmatter support.
  - Navigation generation based on page structure.
  - Static file copying and output directory management.
- Added templates for base layout, pages, and portal.
- Created a CSS file for styling and a JavaScript file for interactive features like language selection and theme toggling.
- Updated documentation source with new configuration and example pages in English and Japanese.
- Added a `justfile` target for building the documentation site.

* Add language/theme toggle functionality

- Created a new Japanese tour index page at docs/ja/tour/index.html
- Implemented navigation links for various sections of the cpp-httplib tutorial
- Added a language selector to switch between English and Japanese
- Introduced theme toggle functionality to switch between light and dark modes
- Added mobile sidebar toggle for better navigation on smaller screens
This commit is contained in:
yhirose
2026-02-28 14:45:40 -05:00
committed by GitHub
parent 85b18a9c64
commit 797758a742
66 changed files with 12361 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs-src/pages/en/cookbook/index.md Normal file
View File

@@ -0,0 +1,8 @@
---
title: "Cookbook"
order: 1
---
This section is under construction.
Check back soon for a collection of recipes organized by topic.

21
docs-src/pages/en/index.md Normal file
View File

@@ -0,0 +1,21 @@
---
title: "cpp-httplib"
order: 0
---
[cpp-httplib](https://github.com/yhirose/cpp-httplib) is an HTTP/HTTPS library for C++. Just copy a single header file, [`httplib.h`](https://github.com/yhirose/cpp-httplib/raw/refs/tags/latest/httplib.h), and you're ready to go.
When you need a quick HTTP server or client in C++, you want something that just works. That's exactly why I built cpp-httplib. You can start writing both servers and clients in just a few lines of code.
The API uses a lambda-based design that feels natural. It runs anywhere you have a C++11 or later compiler. Windows, macOS, Linux — use whatever environment you already have.
HTTPS works too. Just link OpenSSL or mbedTLS, and both server and client gain TLS support. Content-Encoding (gzip, Brotli, etc.), file uploads, and other features you actually need in real-world development are all included. WebSocket is also supported.
Under the hood, it uses blocking I/O with a thread pool. It's not built for handling massive numbers of simultaneous connections. But for API servers, embedded HTTP in tools, mock servers for testing, and many other use cases, it delivers solid performance.
"Solve today's problem, today." That's the kind of simplicity cpp-httplib aims for.
## Documentation
- [A Tour of cpp-httplib](tour/) — A step-by-step tutorial covering the basics. Start here if you're new
- [Cookbook](cookbook/) — A collection of recipes organized by topic. Jump to whatever you need

88
docs-src/pages/en/tour/01-getting-started.md Normal file
View File

@@ -0,0 +1,88 @@
---
title: "Getting Started"
order: 1
---
All you need to get started with cpp-httplib is `httplib.h` and a C++ compiler. Let's download the file and get a Hello World server running.
## Getting httplib.h
You can download it directly from GitHub. Always use the latest version.
```sh
curl -LO https://github.com/yhirose/cpp-httplib/raw/refs/tags/latest/httplib.h
```
Place the downloaded `httplib.h` in your project directory and you're good to go.
## Setting Up Your Compiler
| OS | Development Environment | Setup |
| -- | ----------------------- | ----- |
| macOS | Apple Clang | Xcode Command Line Tools (`xcode-select --install`) |
| Ubuntu | clang++ or g++ | `apt install clang` or `apt install g++` |
| Windows | MSVC | Visual Studio 2022 or later (install with C++ components) |
## Hello World Server
Save the following code as `server.cpp`.
```cpp
#include "httplib.h"
int main() {
httplib::Server svr;
svr.Get("/", [](const httplib::Request&, httplib::Response& res) {
res.set_content("Hello, World!", "text/plain");
});
svr.listen("0.0.0.0", 8080);
}
```
In just a few lines, you have a server that responds to HTTP requests.
## Compiling and Running
The sample code in this tutorial is written in C++17 for cleaner, more concise code. cpp-httplib itself can compile with C++11 as well.
```sh
# macOS
clang++ -std=c++17 -o server server.cpp
# Linux
# `-pthread`: cpp-httplib uses threads internally
clang++ -std=c++17 -pthread -o server server.cpp
# Windows (Developer Command Prompt)
# `/EHsc`: Enable C++ exception handling
cl /EHsc /std:c++17 server.cpp
```
Once it compiles, run it.
```sh
# macOS / Linux
./server
# Windows
server.exe
```
Open `http://localhost:8080` in your browser. If you see "Hello, World!", you're all set.
You can also verify with `curl`.
```sh
curl http://localhost:8080/
# Hello, World!
```
To stop the server, press `Ctrl+C` in your terminal.
## Next Steps
Now you know the basics of running a server. Next, let's look at the client side. cpp-httplib also comes with HTTP client functionality.
**Next:** [Basic Client](../02-basic-client)

266
docs-src/pages/en/tour/02-basic-client.md Normal file
View File

@@ -0,0 +1,266 @@
---
title: "Basic Client"
order: 2
---
cpp-httplib isn't just for servers -- it also comes with a full HTTP client. Let's use `httplib::Client` to send GET and POST requests.
## Preparing a Test Server
To try out the client, you need a server that accepts requests. Save the following code, then compile and run it the same way you did in the previous chapter. We'll cover the server details in the next chapter.
```cpp
#include "httplib.h"
#include <iostream>
int main() {
httplib::Server svr;
svr.Get("/hi", [](const auto &, auto &res) {
res.set_content("Hello!", "text/plain");
});
svr.Get("/search", [](const auto &req, auto &res) {
auto q = req.get_param_value("q");
res.set_content("Query: " + q, "text/plain");
});
svr.Post("/post", [](const auto &req, auto &res) {
res.set_content(req.body, "text/plain");
});
svr.Post("/submit", [](const auto &req, auto &res) {
std::string result;
for (auto &[key, val] : req.params) {
result += key + " = " + val + "\n";
}
res.set_content(result, "text/plain");
});
svr.Post("/upload", [](const auto &req, auto &res) {
auto f = req.form.get_file("file");
auto content = f.filename + " (" + std::to_string(f.content.size()) + " bytes)";
res.set_content(content, "text/plain");
});
svr.Get("/users/:id", [](const auto &req, auto &res) {
auto id = req.path_params.at("id");
res.set_content("User ID: " + id, "text/plain");
});
svr.Get(R"(/files/(\d+))", [](const auto &req, auto &res) {
auto id = req.matches[1];
res.set_content("File ID: " + std::string(id), "text/plain");
});
std::cout << "Listening on port 8080..." << std::endl;
svr.listen("0.0.0.0", 8080);
}
```
## GET Request
Once the server is running, open a separate terminal and give it a try. Let's start with the simplest GET request.
```cpp
#include "httplib.h"
#include <iostream>
int main() {
httplib::Client cli("http://localhost:8080");
auto res = cli.Get("/hi");
if (res) {
std::cout << res->status << std::endl; // 200
std::cout << res->body << std::endl; // Hello!
}
}
```
Pass the server address to the `httplib::Client` constructor, then call `Get()` to send a request. You can retrieve the status code and body from the returned `res`.
Here's the equivalent `curl` command.
```sh
curl http://localhost:8080/hi
# Hello!
```
## Checking the Response
A response contains header information in addition to the status code and body.
```cpp
auto res = cli.Get("/hi");
if (res) {
// Status code
std::cout << res->status << std::endl; // 200
// Body
std::cout << res->body << std::endl; // Hello!
// Headers
std::cout << res->get_header_value("Content-Type") << std::endl; // text/plain
}
```
`res->body` is a `std::string`, so if you want to parse a JSON response, you can pass it directly to a JSON library like [nlohmann/json](https://github.com/nlohmann/json).
## Query Parameters
To add query parameters to a GET request, you can either write them directly in the URL or use `httplib::Params`.
```cpp
auto res = cli.Get("/search", httplib::Params{{"q", "cpp-httplib"}});
if (res) {
std::cout << res->body << std::endl; // Query: cpp-httplib
}
```
`httplib::Params` automatically URL-encodes special characters for you.
```sh
curl "http://localhost:8080/search?q=cpp-httplib"
# Query: cpp-httplib
```
## Path Parameters
When values are embedded directly in the URL path, no special client API is needed. Just pass the path to `Get()` as-is.
```cpp
auto res = cli.Get("/users/42");
if (res) {
std::cout << res->body << std::endl; // User ID: 42
}
```
```sh
curl http://localhost:8080/users/42
# User ID: 42
```
The test server also has a `/files/(\d+)` route that uses a regex to accept numeric IDs only.
```cpp
auto res = cli.Get("/files/42");
if (res) {
std::cout << res->body << std::endl; // File ID: 42
}
```
```sh
curl http://localhost:8080/files/42
# File ID: 42
```
Pass a non-numeric ID like `/files/abc` and you'll get a 404. We'll cover how that works in the next chapter.
## Request Headers
To add custom HTTP headers, pass an `httplib::Headers` object. This works with both `Get()` and `Post()`.
```cpp
auto res = cli.Get("/hi", httplib::Headers{
{"Authorization", "Bearer my-token"}
});
```
```sh
curl -H "Authorization: Bearer my-token" http://localhost:8080/hi
```
## POST Request
Let's POST some text data. Pass the body as the second argument to `Post()` and the Content-Type as the third.
```cpp
auto res = cli.Post("/post", "Hello, Server!", "text/plain");
if (res) {
std::cout << res->status << std::endl; // 200
std::cout << res->body << std::endl; // Hello, Server!
}
```
The test server's `/post` endpoint echoes the body back, so you get the same string you sent.
```sh
curl -X POST -H "Content-Type: text/plain" -d "Hello, Server!" http://localhost:8080/post
# Hello, Server!
```
## Sending Form Data
You can send key-value pairs just like an HTML form. Use `httplib::Params` for this.
```cpp
auto res = cli.Post("/submit", httplib::Params{
{"name", "Alice"},
{"age", "30"}
});
if (res) {
std::cout << res->body << std::endl;
// age = 30
// name = Alice
}
```
This sends the data in `application/x-www-form-urlencoded` format.
```sh
curl -X POST -d "name=Alice&age=30" http://localhost:8080/submit
```
## POSTing a File
To upload a file, use `httplib::UploadFormDataItems` to send it as multipart form data.
```cpp
auto res = cli.Post("/upload", httplib::UploadFormDataItems{
{"file", "Hello, File!", "hello.txt", "text/plain"}
});
if (res) {
std::cout << res->body << std::endl; // hello.txt (12 bytes)
}
```
Each element in `UploadFormDataItems` has four fields: `{name, content, filename, content_type}`.
```sh
curl -F "file=Hello, File!;filename=hello.txt;type=text/plain" http://localhost:8080/upload
```
## Error Handling
Network communication can fail -- the server might not be reachable. Always check whether `res` is valid.
```cpp
httplib::Client cli("http://localhost:9999"); // Non-existent port
auto res = cli.Get("/hi");
if (!res) {
// Connection error
std::cout << "Error: " << httplib::to_string(res.error()) << std::endl;
// Error: Connection
return 1;
}
// If we reach here, we have a response
if (res->status != 200) {
std::cout << "HTTP Error: " << res->status << std::endl;
return 1;
}
std::cout << res->body << std::endl;
```
There are two levels of errors.
- **Connection error**: The client couldn't reach the server. `res` evaluates to false, and you can call `res.error()` to find out what went wrong.
- **HTTP error**: The server returned an error status (404, 500, etc.). `res` evaluates to true, but you need to check `res->status`.
## Next Steps
Now you know how to send requests from a client. Next, let's take a closer look at the server side. We'll dig into routing, path parameters, and more.
**Next:** [Basic Server](../03-basic-server)

280
docs-src/pages/en/tour/03-basic-server.md Normal file
View File

@@ -0,0 +1,280 @@
---
title: "Basic Server"
order: 3
---
In the previous chapter, you sent requests from a client to a test server. Now let's walk through how that server actually works.
## Starting the Server
Once you've registered your routes, call `svr.listen()` to start the server.
```cpp
svr.listen("0.0.0.0", 8080);
```
The first argument is the host, and the second is the port. `"0.0.0.0"` listens on all network interfaces. Use `"127.0.0.1"` if you want to accept connections from your own machine only.
`listen()` is a blocking call. It won't return until the server stops. The server keeps running until you press `Ctrl+C` in your terminal or call `svr.stop()` from another thread.
## Routing
Routing is the heart of any server. It's how you tell cpp-httplib: when a request comes in for this URL with this HTTP method, run this code.
```cpp
httplib::Server svr;
svr.Get("/hi", [](const httplib::Request &req, httplib::Response &res) {
res.set_content("Hello!", "text/plain");
});
```
`svr.Get()` registers a handler for GET requests. The first argument is the path, the second is the handler function. When a GET request arrives at `/hi`, your lambda runs.
There's a method for each HTTP verb.
```cpp
svr.Get("/path", handler); // GET
svr.Post("/path", handler); // POST
svr.Put("/path", handler); // PUT
svr.Delete("/path", handler); // DELETE
```
The handler signature is `(const httplib::Request &req, httplib::Response &res)`. You can use `auto` to keep it short.
```cpp
svr.Get("/hi", [](const auto &req, auto &res) {
res.set_content("Hello!", "text/plain");
});
```
The handler only runs when the path matches. Requests to unregistered paths automatically return 404.
## The Request Object
The first parameter `req` gives you everything the client sent.
### Body
`req.body` holds the request body as a `std::string`.
```cpp
svr.Post("/post", [](const auto &req, auto &res) {
// Echo the body back to the client
res.set_content(req.body, "text/plain");
});
```
### Headers
Use `req.get_header_value()` to read a request header.
```cpp
svr.Get("/check", [](const auto &req, auto &res) {
auto auth = req.get_header_value("Authorization");
res.set_content("Auth: " + auth, "text/plain");
});
```
### Query Parameters and Form Data
`req.get_param_value()` retrieves a parameter by name. It works for both GET query parameters and POST form data.
```cpp
svr.Get("/search", [](const auto &req, auto &res) {
auto q = req.get_param_value("q");
res.set_content("Query: " + q, "text/plain");
});
```
A request to `/search?q=cpp-httplib` gives you `"cpp-httplib"` for `q`.
To loop over all parameters, use `req.params`.
```cpp
svr.Post("/submit", [](const auto &req, auto &res) {
std::string result;
for (auto &[key, val] : req.params) {
result += key + " = " + val + "\n";
}
res.set_content(result, "text/plain");
});
```
### File Uploads
Files uploaded via multipart form data are available through `req.form.get_file()`.
```cpp
svr.Post("/upload", [](const auto &req, auto &res) {
auto f = req.form.get_file("file");
auto content = f.filename + " (" + std::to_string(f.content.size()) + " bytes)";
res.set_content(content, "text/plain");
});
```
`f.filename` gives you the filename, and `f.content` gives you the file data.
## Path Parameters
Sometimes you want to capture part of the URL as a variable -- for example, the `42` in `/users/42`. Use the `:param` syntax to do that.
```cpp
svr.Get("/users/:id", [](const auto &req, auto &res) {
auto id = req.path_params.at("id");
res.set_content("User ID: " + id, "text/plain");
});
```
A request to `/users/42` gives you `"42"` from `req.path_params.at("id")`. `/users/100` gives you `"100"`.
You can capture multiple segments at once.
```cpp
svr.Get("/users/:user_id/posts/:post_id", [](const auto &req, auto &res) {
auto user_id = req.path_params.at("user_id");
auto post_id = req.path_params.at("post_id");
res.set_content("User: " + user_id + ", Post: " + post_id, "text/plain");
});
```
### Regex Patterns
You can also write a regular expression directly in the path instead of `:param`. Capture group values are available via `req.matches`, which is a `std::smatch`.
```cpp
// Only accept numeric IDs
svr.Get(R"(/files/(\d+))", [](const auto &req, auto &res) {
auto id = req.matches[1]; // First capture group
res.set_content("File ID: " + std::string(id), "text/plain");
});
```
`/files/42` matches, but `/files/abc` doesn't. This is handy when you want to constrain what values are accepted.
## Building a Response
The second parameter `res` is how you send data back to the client.
### Body and Content-Type
`res.set_content()` sets the body and Content-Type. That's all you need for a 200 response.
```cpp
svr.Get("/hi", [](const auto &req, auto &res) {
res.set_content("Hello!", "text/plain");
});
```
### Status Code
To return a different status code, assign to `res.status`.
```cpp
svr.Get("/not-found", [](const auto &req, auto &res) {
res.status = 404;
res.set_content("Not found", "text/plain");
});
```
### Response Headers
Add response headers with `res.set_header()`.
```cpp
svr.Get("/with-header", [](const auto &req, auto &res) {
res.set_header("X-Custom", "my-value");
res.set_content("Hello!", "text/plain");
});
```
## Walking Through the Test Server
Now let's use what we've learned to read through the test server from the previous chapter.
### GET /hi
```cpp
svr.Get("/hi", [](const auto &, auto &res) {
res.set_content("Hello!", "text/plain");
});
```
The simplest possible handler. We don't need any information from the request, so the `req` parameter is left unnamed. It just returns `"Hello!"`.
### GET /search
```cpp
svr.Get("/search", [](const auto &req, auto &res) {
auto q = req.get_param_value("q");
res.set_content("Query: " + q, "text/plain");
});
```
`req.get_param_value("q")` pulls out the query parameter `q`. A request to `/search?q=cpp-httplib` returns `"Query: cpp-httplib"`.
### POST /post
```cpp
svr.Post("/post", [](const auto &req, auto &res) {
res.set_content(req.body, "text/plain");
});
```
An echo server. Whatever body the client sends, `req.body` holds it, and we send it straight back.
### POST /submit
```cpp
svr.Post("/submit", [](const auto &req, auto &res) {
std::string result;
for (auto &[key, val] : req.params) {
result += key + " = " + val + "\n";
}
res.set_content(result, "text/plain");
});
```
Loops over the form data in `req.params` using structured bindings (`auto &[key, val]`) to unpack each key-value pair.
### POST /upload
```cpp
svr.Post("/upload", [](const auto &req, auto &res) {
auto f = req.form.get_file("file");
auto content = f.filename + " (" + std::to_string(f.content.size()) + " bytes)";
res.set_content(content, "text/plain");
});
```
Receives a file uploaded via multipart form data. `req.form.get_file("file")` fetches the field named `"file"`, and we respond with the filename and size.
### GET /users/:id
```cpp
svr.Get("/users/:id", [](const auto &req, auto &res) {
auto id = req.path_params.at("id");
res.set_content("User ID: " + id, "text/plain");
});
```
`:id` is the path parameter. `req.path_params.at("id")` retrieves its value. `/users/42` gives you `"42"`, `/users/alice` gives you `"alice"`.
### GET /files/(\d+)
```cpp
svr.Get(R"(/files/(\d+))", [](const auto &req, auto &res) {
auto id = req.matches[1];
res.set_content("File ID: " + std::string(id), "text/plain");
});
```
The regex `(\d+)` matches numeric IDs only. `/files/42` hits this handler, but `/files/abc` returns 404. `req.matches[1]` retrieves the first capture group.
## Next Steps
You now have the full picture of how a server works. Routing, reading requests, building responses -- that's enough to build a real API server.
Next, let's look at serving static files. We'll build a server that delivers HTML and CSS.
**Next:** [Static File Server](../04-static-file-server)

134
docs-src/pages/en/tour/04-static-file-server.md Normal file
View File

@@ -0,0 +1,134 @@
---
title: "Static File Server"
order: 4
---
cpp-httplib can serve static files too — HTML, CSS, images, you name it. No complicated configuration required. One call to `set_mount_point()` is all it takes.
## The basics of set_mount_point
Let's jump right in. `set_mount_point()` maps a URL path to a local directory.
```cpp
#include "httplib.h"
#include <iostream>
int main() {
httplib::Server svr;
svr.set_mount_point("/", "./html");
std::cout << "Listening on port 8080..." << std::endl;
svr.listen("0.0.0.0", 8080);
}
```
The first argument is the URL mount point. The second is the local directory path. In this example, requests to `/` are served from the `./html` directory.
Let's try it out. First, create an `html` directory and add an `index.html` file.
```sh
mkdir html
```
```html
<!DOCTYPE html>
<html>
<head><title>My Page</title></head>
<body>
<h1>Hello from cpp-httplib!</h1>
<p>This is a static file.</p>
</body>
</html>
```
Compile and start the server.
```sh
g++ -std=c++17 -o server server.cpp -pthread
./server
```
Open `http://localhost:8080` in your browser. You should see the contents of `html/index.html`. Visiting `http://localhost:8080/index.html` returns the same page.
You can also access it with the client code from the previous chapter, or with `curl`.
```cpp
httplib::Client cli("http://localhost:8080");
auto res = cli.Get("/");
if (res) {
std::cout << res->body << std::endl; // HTML is displayed
}
```
```sh
curl http://localhost:8080
```
## Multiple mount points
You can call `set_mount_point()` as many times as you like. Each URL path gets its own directory.
```cpp
svr.set_mount_point("/", "./public");
svr.set_mount_point("/assets", "./static/assets");
svr.set_mount_point("/docs", "./documentation");
```
A request to `/assets/style.css` serves `./static/assets/style.css`. A request to `/docs/guide.html` serves `./documentation/guide.html`.
## Combining with handlers
Static file serving and routing handlers — the kind you learned about in the previous chapter — work side by side.
```cpp
httplib::Server svr;
// API endpoint
svr.Get("/api/hello", [](const auto &, auto &res) {
res.set_content(R"({"message":"Hello!"})", "application/json");
});
// Static file serving
svr.set_mount_point("/", "./public");
svr.listen("0.0.0.0", 8080);
```
Handlers take priority. The handler responds to `/api/hello`. For every other path, the server looks for a file in `./public`.
## Adding response headers
Pass headers as the third argument to `set_mount_point()` and they get attached to every static file response. This is great for cache control.
```cpp
svr.set_mount_point("/", "./public", {
{"Cache-Control", "max-age=3600"}
});
```
With this in place, the browser caches served files for one hour.
## A Dockerfile for your static file server
The cpp-httplib repository includes a `Dockerfile` built for static file serving. We also publish a pre-built image on Docker Hub, so you can get up and running with a single command.
```sh
> docker run -p 8080:80 -v ./my-site:/html yhirose4dockerhub/cpp-httplib-server
Serving HTTP on 0.0.0.0:80
Mount point: / -> ./html
Press Ctrl+C to shutdown gracefully...
192.168.65.1 - - [22/Feb/2026:12:00:00 +0000] "GET / HTTP/1.1" 200 256 "-" "Mozilla/5.0 ..."
192.168.65.1 - - [22/Feb/2026:12:00:00 +0000] "GET /style.css HTTP/1.1" 200 1024 "-" "Mozilla/5.0 ..."
192.168.65.1 - - [22/Feb/2026:12:00:01 +0000] "GET /favicon.ico HTTP/1.1" 404 152 "-" "Mozilla/5.0 ..."
```
Everything in your `./my-site` directory gets served on port 8080. The access log follows the same format as NGINX, so you can see exactly what's happening.
## What's next
You can now serve static files. A web server that delivers HTML, CSS, and JavaScript — built with this little code.
Next, let's encrypt your connections with HTTPS. We'll start by setting up a TLS library.
**Next:** [TLS Setup](../05-tls-setup)

88
docs-src/pages/en/tour/05-tls-setup.md Normal file
View File

@@ -0,0 +1,88 @@
---
title: "TLS Setup"
order: 5
---
So far we've been using plain HTTP, but in the real world, HTTPS is the norm. To use HTTPS with cpp-httplib, you need a TLS library.
In this tour, we'll use OpenSSL. It's the most widely used option, and you'll find plenty of resources online.
## Installing OpenSSL
Install it for your OS.
| OS | How to install |
| -- | -------------- |
| macOS | [Homebrew](https://brew.sh/) (`brew install openssl`) |
| Ubuntu / Debian | `sudo apt install libssl-dev` |
| Windows | [vcpkg](https://vcpkg.io/) (`vcpkg install openssl`) |
## Compile Options
To enable TLS, define the `CPPHTTPLIB_OPENSSL_SUPPORT` macro when compiling. You'll need a few extra options compared to the previous chapters.
```sh
# macOS (Homebrew)
clang++ -std=c++17 -DCPPHTTPLIB_OPENSSL_SUPPORT \
-I$(brew --prefix openssl)/include \
-L$(brew --prefix openssl)/lib \
-lssl -lcrypto \
-framework CoreFoundation -framework Security \
-o server server.cpp
# Linux
clang++ -std=c++17 -pthread -DCPPHTTPLIB_OPENSSL_SUPPORT \
-lssl -lcrypto \
-o server server.cpp
# Windows (Developer Command Prompt)
cl /EHsc /std:c++17 /DCPPHTTPLIB_OPENSSL_SUPPORT server.cpp libssl.lib libcrypto.lib
```
Let's look at what each option does.
- **`-DCPPHTTPLIB_OPENSSL_SUPPORT`** — Defines the macro that enables TLS support
- **`-lssl -lcrypto`** — Links the OpenSSL libraries
- **`-I` / `-L`** (macOS only) — Points to the Homebrew OpenSSL paths
- **`-framework CoreFoundation -framework Security`** (macOS only) — Needed to automatically load system certificates from the Keychain
## Verifying the Setup
Let's make sure everything works. Here's a simple program that passes an HTTPS URL to `httplib::Client`.
```cpp
#define CPPHTTPLIB_OPENSSL_SUPPORT
#include "httplib.h"
#include <iostream>
int main() {
httplib::Client cli("https://www.google.com");
auto res = cli.Get("/");
if (res) {
std::cout << "Status: " << res->status << std::endl;
} else {
std::cout << "Error: " << httplib::to_string(res.error()) << std::endl;
}
}
```
Compile and run it. If you see `Status: 200`, your setup is complete.
## Other TLS Backends
cpp-httplib also supports Mbed TLS and wolfSSL in addition to OpenSSL. You can switch between them just by changing the macro definition and linked libraries.
| Backend | Macro | Libraries to link |
| :--- | :--- | :--- |
| OpenSSL | `CPPHTTPLIB_OPENSSL_SUPPORT` | `libssl`, `libcrypto` |
| Mbed TLS | `CPPHTTPLIB_MBEDTLS_SUPPORT` | `libmbedtls`, `libmbedx509`, `libmbedcrypto` |
| wolfSSL | `CPPHTTPLIB_WOLFSSL_SUPPORT` | `libwolfssl` |
This tour assumes OpenSSL, but the API is the same regardless of which backend you choose.
## Next Step
You're all set with TLS. Next, let's send a request to an HTTPS site.
**Next:** [HTTPS Client](../06-https-client)

122
docs-src/pages/en/tour/06-https-client.md Normal file
View File

@@ -0,0 +1,122 @@
---
title: "HTTPS Client"
order: 6
---
In the previous chapter, you set up OpenSSL. Now let's put it to use with an HTTPS client. You can use the same `httplib::Client` from Chapter 2. Just pass a URL with the `https://` scheme to the constructor.
## GET Request
Let's try accessing a real HTTPS site.
```cpp
#define CPPHTTPLIB_OPENSSL_SUPPORT
#include "httplib.h"
#include <iostream>
int main() {
httplib::Client cli("https://nghttp2.org");
auto res = cli.Get("/");
if (res) {
std::cout << res->status << std::endl; // 200
std::cout << res->body.substr(0, 100) << std::endl; // First 100 chars of the HTML
} else {
std::cout << "Error: " << httplib::to_string(res.error()) << std::endl;
}
}
```
In Chapter 2, you wrote `httplib::Client cli("http://localhost:8080")`. All you need to change is the scheme to `https://`. Every API you learned in Chapter 2 -- `Get()`, `Post()`, and so on -- works exactly the same way.
```sh
curl https://nghttp2.org/
```
## Specifying a Port
The default port for HTTPS is 443. If you need a different port, include it in the URL.
```cpp
httplib::Client cli("https://localhost:8443");
```
## CA Certificate Verification
When connecting over HTTPS, `httplib::Client` verifies the server certificate by default. It only connects to servers whose certificate was issued by a trusted CA (Certificate Authority).
CA certificates are loaded automatically from the Keychain on macOS, the system CA certificate store on Linux, and the Windows certificate store on Windows. In most cases, no extra configuration is needed.
### Specifying a CA Certificate File
On some environments, the system CA certificates may not be found. In that case, use `set_ca_cert_path()` to specify the path directly.
```cpp
httplib::Client cli("https://nghttp2.org");
cli.set_ca_cert_path("/etc/ssl/certs/ca-certificates.crt");
auto res = cli.Get("/");
```
```sh
curl --cacert /etc/ssl/certs/ca-certificates.crt https://nghttp2.org/
```
### Disabling Certificate Verification
During development, you might want to connect to a server with a self-signed certificate. You can disable verification for that.
```cpp
httplib::Client cli("https://localhost:8443");
cli.enable_server_certificate_verification(false);
auto res = cli.Get("/");
```
```sh
curl -k https://localhost:8443/
```
Never disable this in production. It opens you up to man-in-the-middle attacks.
## Following Redirects
When accessing HTTPS sites, you'll often encounter redirects. For example, `http://` to `https://`, or a bare domain to `www`.
By default, redirects are not followed. You can check the redirect target in the `Location` header.
```cpp
httplib::Client cli("https://nghttp2.org");
auto res = cli.Get("/httpbin/redirect/3");
if (res) {
std::cout << res->status << std::endl; // 302
std::cout << res->get_header_value("Location") << std::endl;
}
```
```sh
curl https://nghttp2.org/httpbin/redirect/3
```
Call `set_follow_location(true)` to automatically follow redirects and get the final response.
```cpp
httplib::Client cli("https://nghttp2.org");
cli.set_follow_location(true);
auto res = cli.Get("/httpbin/redirect/3");
if (res) {
std::cout << res->status << std::endl; // 200 (the final response)
}
```
```sh
curl -L https://nghttp2.org/httpbin/redirect/3
```
## Next Steps
Now you know how to use the HTTPS client. Next, let's set up your own HTTPS server. We'll start with creating a self-signed certificate.
**Next:** [HTTPS Server](../07-https-server)

124
docs-src/pages/en/tour/07-https-server.md Normal file
View File

@@ -0,0 +1,124 @@
---
title: "HTTPS Server"
order: 7
---
In the previous chapter, you used an HTTPS client. Now let's set up your own HTTPS server. Just swap `httplib::Server` from Chapter 3 with `httplib::SSLServer`.
A TLS server needs a server certificate and a private key, though. Let's get those ready first.
## Creating a Self-Signed Certificate
For development and testing, a self-signed certificate works just fine. You can generate one quickly with an OpenSSL command.
```sh
openssl req -x509 -noenc -keyout key.pem -out cert.pem -subj /CN=localhost
```
This creates two files:
- **`cert.pem`** — Server certificate
- **`key.pem`** — Private key
## A Minimal HTTPS Server
Once you have your certificate, let's write the server.
```cpp
#define CPPHTTPLIB_OPENSSL_SUPPORT
#include "httplib.h"
#include <iostream>
int main() {
httplib::SSLServer svr("cert.pem", "key.pem");
svr.Get("/", [](const auto &, auto &res) {
res.set_content("Hello, HTTPS!", "text/plain");
});
std::cout << "Listening on https://localhost:8443" << std::endl;
svr.listen("0.0.0.0", 8443);
}
```
Just pass the certificate and private key paths to the `httplib::SSLServer` constructor. The routing API is exactly the same as `httplib::Server` from Chapter 3.
Compile and start it up.
## Testing It Out
With the server running, try accessing it with `curl`. Since we're using a self-signed certificate, add the `-k` option to skip certificate verification.
```sh
curl -k https://localhost:8443/
# Hello, HTTPS!
```
If you open `https://localhost:8443` in a browser, you'll see a "This connection is not secure" warning. That's expected with a self-signed certificate. Just proceed past it.
## Connecting from a Client
Let's connect using `httplib::Client` from the previous chapter. There are two ways to connect to a server with a self-signed certificate.
### Option 1: Disable Certificate Verification
This is the quick and easy approach for development.
```cpp
#define CPPHTTPLIB_OPENSSL_SUPPORT
#include "httplib.h"
#include <iostream>
int main() {
httplib::Client cli("https://localhost:8443");
cli.enable_server_certificate_verification(false);
auto res = cli.Get("/");
if (res) {
std::cout << res->body << std::endl; // Hello, HTTPS!
}
}
```
### Option 2: Specify the Self-Signed Certificate as a CA Certificate
This is the safer approach. You tell the client to trust `cert.pem` as a CA certificate.
```cpp
#define CPPHTTPLIB_OPENSSL_SUPPORT
#include "httplib.h"
#include <iostream>
int main() {
httplib::Client cli("https://localhost:8443");
cli.set_ca_cert_path("cert.pem");
auto res = cli.Get("/");
if (res) {
std::cout << res->body << std::endl; // Hello, HTTPS!
}
}
```
This way, only connections to the server with that specific certificate are allowed, preventing impersonation. Use this approach whenever possible, even in test environments.
## Comparing Server and SSLServer
The `httplib::Server` API you learned in Chapter 3 works exactly the same with `httplib::SSLServer`. The only difference is the constructor.
| | `httplib::Server` | `httplib::SSLServer` |
| -- | ------------------ | -------------------- |
| Constructor | No arguments | Certificate and private key paths |
| Protocol | HTTP | HTTPS |
| Port (convention) | 8080 | 8443 |
| Routing | Same | Same |
To switch an HTTP server to HTTPS, just change the constructor.
## Next Steps
Your HTTPS server is up and running. You now have the basics of both HTTP/HTTPS clients and servers covered.
Next, let's look at the WebSocket support that was recently added to cpp-httplib.
**Next:** [WebSocket](../08-websocket)

139
docs-src/pages/en/tour/08-websocket.md Normal file
View File

@@ -0,0 +1,139 @@
---
title: "WebSocket"
order: 8
---
cpp-httplib supports WebSocket as well. Unlike HTTP request/response, WebSocket lets the server and client exchange messages in both directions. It's great for chat apps and real-time notifications.
Let's build an echo server and client right away.
## Echo Server
Here's an echo server that sends back whatever message it receives.
```cpp
#include "httplib.h"
#include <iostream>
int main() {
httplib::Server svr;
svr.WebSocket("/ws", [](const httplib::Request &, httplib::ws::WebSocket &ws) {
std::string msg;
while (ws.read(msg)) {
ws.send(msg); // Send back the received message as-is
}
});
std::cout << "Listening on port 8080..." << std::endl;
svr.listen("0.0.0.0", 8080);
}
```
You register a WebSocket handler with `svr.WebSocket()`. It works just like `svr.Get()` and `svr.Post()` from Chapter 3.
Inside the handler, `ws.read(msg)` waits for a message. When the connection closes, `read()` returns `false`, so the loop exits. `ws.send(msg)` sends a message back.
## Connecting from a Client
Let's connect to the server using `httplib::ws::WebSocketClient`.
```cpp
#include "httplib.h"
#include <iostream>
int main() {
httplib::ws::WebSocketClient client("ws://localhost:8080/ws");
if (!client.connect()) {
std::cout << "Connection failed" << std::endl;
return 1;
}
// Send a message
client.send("Hello, WebSocket!");
// Receive a response from the server
std::string msg;
if (client.read(msg)) {
std::cout << msg << std::endl; // Hello, WebSocket!
}
client.close();
}
```
Pass a URL in `ws://host:port/path` format to the constructor. Call `connect()` to start the connection, then use `send()` and `read()` to exchange messages.
## Text and Binary
WebSocket has two types of messages: text and binary. You can tell them apart by the return value of `read()`.
```cpp
svr.WebSocket("/ws", [](const httplib::Request &, httplib::ws::WebSocket &ws) {
std::string msg;
httplib::ws::ReadResult ret;
while ((ret = ws.read(msg))) {
if (ret == httplib::ws::Binary) {
ws.send(msg.data(), msg.size()); // Send as binary
} else {
ws.send(msg); // Send as text
}
}
});
```
- `ws.send(const std::string &)` — sends as a text message
- `ws.send(const char *, size_t)` — sends as a binary message
The client-side API is the same.
## Accessing Request Information
You can read HTTP request information from the handshake through the first argument `req` in the handler. This is handy for checking authentication tokens.
```cpp
svr.WebSocket("/ws", [](const httplib::Request &req, httplib::ws::WebSocket &ws) {
auto token = req.get_header_value("Authorization");
if (token.empty()) {
ws.close(httplib::ws::CloseStatus::PolicyViolation, "unauthorized");
return;
}
std::string msg;
while (ws.read(msg)) {
ws.send(msg);
}
});
```
## Using WSS
WebSocket over HTTPS (WSS) is also supported. On the server side, just register a WebSocket handler on `httplib::SSLServer`.
```cpp
httplib::SSLServer svr("cert.pem", "key.pem");
svr.WebSocket("/ws", [](const httplib::Request &, httplib::ws::WebSocket &ws) {
std::string msg;
while (ws.read(msg)) {
ws.send(msg);
}
});
svr.listen("0.0.0.0", 8443);
```
On the client side, use the `wss://` scheme.
```cpp
httplib::ws::WebSocketClient client("wss://localhost:8443/ws");
```
## Next Steps
Now you know the basics of WebSocket. This wraps up the Tour.
The next page gives you a summary of features we didn't cover in the Tour.
**Next:** [What's Next](../09-whats-next)

228
docs-src/pages/en/tour/09-whats-next.md Normal file
View File

@@ -0,0 +1,228 @@
---
title: "What's Next"
order: 9
---
Great job finishing the Tour! You now have a solid grasp of the cpp-httplib basics. But there's a lot more to explore. Here's a quick overview of features we didn't cover in the Tour, organized by category.
## Streaming API
When you're working with LLM streaming responses or downloading large files, you don't want to load the entire response into memory. Use `stream::Get()` to process data chunk by chunk.
```cpp
httplib::Client cli("http://localhost:11434");
auto result = httplib::stream::Get(cli, "/api/generate");
if (result) {
while (result.next()) {
std::cout.write(result.data(), result.size());
}
}
```
You can also pass a `content_receiver` callback to `Get()`. This approach works with Keep-Alive.
```cpp
httplib::Client cli("http://localhost:8080");
cli.Get("/stream", [](const char *data, size_t len) {
std::cout.write(data, len);
return true;
});
```
On the server side, you have `set_content_provider()` and `set_chunked_content_provider()`. Use the former when you know the size, and the latter when you don't.
```cpp
// With known size (sets Content-Length)
svr.Get("/file", [](const auto &, auto &res) {
auto size = get_file_size("large.bin");
res.set_content_provider(size, "application/octet-stream",
[](size_t offset, size_t length, httplib::DataSink &sink) {
// Send 'length' bytes starting from 'offset'
return true;
});
});
// Unknown size (Chunked Transfer Encoding)
svr.Get("/stream", [](const auto &, auto &res) {
res.set_chunked_content_provider("text/plain",
[](size_t offset, httplib::DataSink &sink) {
sink.write("chunk\n", 6);
return true; // Return false to finish
});
});
```
For uploading large files, `make_file_provider()` comes in handy. It streams the file instead of loading it all into memory.
```cpp
httplib::Client cli("http://localhost:8080");
auto res = cli.Post("/upload", {}, {
httplib::make_file_provider("file", "/path/to/large-file.zip")
});
```
## Server-Sent Events (SSE)
We provide an SSE client as well. It supports automatic reconnection and resuming via `Last-Event-ID`.
```cpp
httplib::Client cli("http://localhost:8080");
httplib::sse::SSEClient sse(cli, "/events");
sse.on_message([](const httplib::sse::SSEMessage &msg) {
std::cout << msg.event << ": " << msg.data << std::endl;
});
sse.start(); // Blocking, with auto-reconnection
```
You can also set separate handlers for each event type.
```cpp
sse.on_event("update", [](const httplib::sse::SSEMessage &msg) {
// Only handles "update" events
});
```
## Authentication
The client has helpers for Basic auth, Bearer Token auth, and Digest auth.
```cpp
httplib::Client cli("https://api.example.com");
cli.set_basic_auth("user", "password");
cli.set_bearer_token_auth("my-token");
```
## Compression
We support compression and decompression with gzip, Brotli, and Zstandard. Define the corresponding macro when you compile.
| Method | Macro |
| -- | -- |
| gzip | `CPPHTTPLIB_ZLIB_SUPPORT` |
| Brotli | `CPPHTTPLIB_BROTLI_SUPPORT` |
| Zstandard | `CPPHTTPLIB_ZSTD_SUPPORT` |
```cpp
httplib::Client cli("https://example.com");
cli.set_compress(true); // Compress request body
cli.set_decompress(true); // Decompress response body
```
## Proxy
You can connect through an HTTP proxy.
```cpp
httplib::Client cli("https://example.com");
cli.set_proxy("proxy.example.com", 8080);
cli.set_proxy_basic_auth("user", "password");
```
## Timeouts
You can set connection, read, and write timeouts individually.
```cpp
httplib::Client cli("https://example.com");
cli.set_connection_timeout(5, 0); // 5 seconds
cli.set_read_timeout(10, 0); // 10 seconds
cli.set_write_timeout(10, 0); // 10 seconds
```
## Keep-Alive
If you're making multiple requests to the same server, enable Keep-Alive. It reuses the TCP connection, which is much more efficient.
```cpp
httplib::Client cli("https://example.com");
cli.set_keep_alive(true);
```
## Server Middleware
You can hook into request processing before and after handlers run.
```cpp
svr.set_pre_routing_handler([](const auto &req, auto &res) {
// Runs before every request
return httplib::Server::HandlerResponse::Unhandled; // Continue to normal routing
});
svr.set_post_routing_handler([](const auto &req, auto &res) {
// Runs after the response is sent
res.set_header("X-Server", "cpp-httplib");
});
```
Use `req.user_data` to pass data from middleware to handlers. This is useful for sharing things like decoded auth tokens.
```cpp
svr.set_pre_routing_handler([](const auto &req, auto &res) {
req.user_data["auth_user"] = std::string("alice");
return httplib::Server::HandlerResponse::Unhandled;
});
svr.Get("/me", [](const auto &req, auto &res) {
auto user = std::any_cast<std::string>(req.user_data.at("auth_user"));
res.set_content("Hello, " + user, "text/plain");
});
```
You can also customize error and exception handlers.
```cpp
svr.set_error_handler([](const auto &req, auto &res) {
res.set_content("Custom Error Page", "text/html");
});
svr.set_exception_handler([](const auto &req, auto &res, std::exception_ptr ep) {
res.status = 500;
res.set_content("Internal Server Error", "text/plain");
});
```
## Logging
You can set a logger on both the server and the client.
```cpp
svr.set_logger([](const auto &req, const auto &res) {
std::cout << req.method << " " << req.path << " " << res.status << std::endl;
});
```
## Unix Domain Socket
In addition to TCP, we support Unix Domain Sockets. You can use them for inter-process communication on the same machine.
```cpp
// Server
httplib::Server svr;
svr.set_address_family(AF_UNIX);
svr.listen("/tmp/httplib.sock", 0);
```
```cpp
// Client
httplib::Client cli("http://localhost");
cli.set_address_family(AF_UNIX);
cli.set_hostname_addr_map({{"localhost", "/tmp/httplib.sock"}});
auto res = cli.Get("/");
```
## Learn More
Want to dig deeper? Check out these resources.
- Cookbook — A collection of recipes for common use cases
- [README](https://github.com/yhirose/cpp-httplib/blob/master/README.md) — Full API reference
- [README-sse](https://github.com/yhirose/cpp-httplib/blob/master/README-sse.md) — How to use Server-Sent Events
- [README-stream](https://github.com/yhirose/cpp-httplib/blob/master/README-stream.md) — How to use the Streaming API
- [README-websocket](https://github.com/yhirose/cpp-httplib/blob/master/README-websocket.md) — How to use the WebSocket server

16
docs-src/pages/en/tour/index.md Normal file
View File

@@ -0,0 +1,16 @@
---
title: "A Tour of cpp-httplib"
order: 1
---
This is a step-by-step tutorial that walks you through the basics of cpp-httplib. Each chapter builds on the previous one, so please read them in order starting from Chapter 1.
1. [Getting Started](01-getting-started) — Get httplib.h and build a Hello World server
2. [Basic Client](02-basic-client) — Send GET/POST requests and use path parameters
3. [Basic Server](03-basic-server) — Routing, path parameters, and building responses
4. [Static File Server](04-static-file-server) — Serve static files
5. [TLS Setup](05-tls-setup) — Set up OpenSSL / mbedTLS
6. [HTTPS Client](06-https-client) — Make requests to HTTPS sites
7. [HTTPS Server](07-https-server) — Build an HTTPS server
8. [WebSocket](08-websocket) — Learn the basics of WebSocket communication
9. [What's Next](09-whats-next) — Explore more features