Cpp-httplib

https://github.com/yhirose/cpp-httplib
Admin
A C++11 single-file header-only cross-platform HTTP/HTTPS library that is easy to set up and use for...
Tokens:368,644
Snippets:2,527
Trust Score:8.4
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Basic Usage Example

Source: https://github.com/yhirose/cpp-httplib/blob/master/README-sse.md

Minimal example: creates client, sets on_message to print data, and starts blocking.

```cpp
httplib::Client cli("http://localhost:8080");
httplib::sse::SSEClient sse(cli, "/events");

sse.on_message([](const httplib::sse::SSEMessage &msg) {
    std::cout << msg.data << std::endl;
});

sse.start();
```

--------------------------------

### Quick Start: Basic SSE Client Setup

Source: https://github.com/yhirose/cpp-httplib/blob/master/README-sse.md

Sets up an SSE client to connect to a local server and listen for messages. Uses on_message to print event type and data, then starts the client in blocking mode with auto-reconnect.

```cpp
httplib::Client cli("http://localhost:8080");
httplib::sse::SSEClient sse(cli, "/events");

sse.on_message([](const httplib::sse::SSEMessage &msg) {
    std::cout << "Event: " << msg.event << std::endl;
    std::cout << "Data: " << msg.data << std::endl;
});

sse.start();  // Blocking, with auto-reconnect
```

--------------------------------

### C++ program to verify TLS setup with httplib::Client

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/05-tls-setup.md

A simple program that creates an httplib::Client with an HTTPS URL and performs a GET request, printing the status or error. Compile and run it; a Status: 200 indicates the setup is complete.

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

--------------------------------

### Run the wsecho example

Source: https://github.com/yhirose/cpp-httplib/blob/master/README-websocket.md

Builds and runs the WebSocket echo server example. Navigate to http://localhost:8080 in a browser after execution.

```bash
cd example && make wsecho && ./wsecho
```

--------------------------------

### Test server for client examples

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/02-basic-client.md

A cpp-httplib server that handles GET and POST endpoints used to test the client. It includes routes for /hi, /search, /post, /submit, /upload, /users/:id, and a regex route /files/(\d+). Compile and run this server before trying the client examples.

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

--------------------------------

### Async with Stop Example

Source: https://github.com/yhirose/cpp-httplib/blob/master/README-sse.md

Starts the client asynchronously, does other work, then stops it. start_async returns immediately.

```cpp
httplib::sse::SSEClient sse(cli, "/events");

sse.on_message([](const httplib::sse::SSEMessage &msg) {
    std::cout << msg.data << std::endl;
});

sse.start_async();  // Returns immediately

// ... do other work ...

sse.stop();  // Stop when done
```

--------------------------------

### Build and start the server

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/llm-app/ch02-rest-api.md

Rebuild the project with CMake and start the translation server.

```bash
cmake --build build -j
./build/translate-server
```

--------------------------------

### Build and install on Windows

Source: https://github.com/yhirose/cpp-httplib/blob/master/CMakeLists.txt

Commands to build and install cpp-httplib on Windows. Requires running the install command with administrator privileges.

```bash
mkdir build
cd build
cmake ..
runas /user:Administrator "cmake --build . --config Release --target install"
```

--------------------------------

### Simple GET request with httplib::Client

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/02-basic-client.md

Creates a client for http://localhost:8080 and sends a GET request to /hi. Prints the status code (200) and body (Hello!). Requires the server to be running.

```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!
    }
}
```

--------------------------------

### Launch the desktop app

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/llm-app/ch06-desktop-app.md

Run the compiled binary to start the app.

```bash
./build/translate-app
```

--------------------------------

### Combine static files with API handlers

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/cookbook/s04-static-files.md

Registers a GET handler for '/api/users' and then sets a mount point for static files. For GET and HEAD requests, mount points are searched first; handlers run only when no file is found, enabling an SPA-friendly setup.

```cpp
svr.Get("/api/users", [](const auto &req, auto &res) {
  res.set_content("[]", "application/json");
});

svr.set_mount_point("/", "./public");
```

--------------------------------

### Privilege drop example with bind_to_port() and listen_after_bind()

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/cookbook/s18-listen-after-bind.md

Binds to port 80 (requires root), drops privileges, then starts accepting. All subsequent request handling runs with reduced privileges.

```cpp
svr.bind_to_port("0.0.0.0", 80);
drop_privileges();
svr.listen_after_bind();
```

--------------------------------

### Start server with svr.listen()

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/03-basic-server.md

Starts the server on all network interfaces at port 8080. listen() is blocking and returns only when the server stops, e.g., via Ctrl+C or svr.stop() from another thread.

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

--------------------------------

### stream::Get() Example

Source: https://github.com/yhirose/cpp-httplib/blob/master/README-stream.md

Shows how to use httplib::stream::Get() for iterator-based streaming. Includes simple GET, GET with custom headers, processing chunks with next()/data()/size(), and reading the entire body with read_all().

```cpp
#include "httplib.h"

httplib::Client cli("http://localhost:8080");
...

// Simple GET
auto result = httplib::stream::Get(cli, "/path");

// GET with custom headers
httplib::Headers headers = {{"Authorization", "Bearer token"}};
auto result = httplib::stream::Get(cli, "/path", headers);

// Process the response
if (result) {
    while (result.next()) {
        process(result.data(), result.size());
    }
}

// Or read entire body at once
auto result2 = httplib::stream::Get(cli, "/path");
if (result2) {
    std::string body = result2.read_all();
}
```

--------------------------------

### Basic GET request with httplib::Client

Source: https://github.com/yhirose/cpp-httplib/blob/master/README.md

Creates a client for localhost:1234 and performs a GET /hi request. Checks for StatusCode::OK_200 and prints the response body; on failure, prints the error via httplib::to_string(err).

```c++
#include <httplib.h>
#include <iostream>

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

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

--------------------------------

### Register GET, POST, PUT, DELETE handlers with httplib::Server

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/cookbook/s01-handlers.md

Shows the basic pattern for registering handlers for each HTTP method. Handlers take (const Request&, Response&) and use res.set_content() and res.status. listen() starts the server and blocks.

```cpp
#include <httplib.h>

int main() {
  httplib::Server svr;

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

  svr.Post("/api/items", [](const httplib::Request &req, httplib::Response &res) {
    // req.body holds the request body
    res.status = 201;
    res.set_content("Created", "text/plain");
  });

  svr.Put("/api/items/1", [](const httplib::Request &req, httplib::Response &res) {
    res.set_content("Updated", "text/plain");
  });

  svr.Delete("/api/items/1", [](const httplib::Request &req, httplib::Response &res) {
    res.status = 204;
  });

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

--------------------------------

### Hello World server in C++

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/01-getting-started.md

Creates a simple HTTP server that responds with 'Hello, World!' on GET requests to '/'. Listens on 0.0.0.0:8080.

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

--------------------------------

### Build and install on Linux/macOS

Source: https://github.com/yhirose/cpp-httplib/blob/master/CMakeLists.txt

Commands to build and install cpp-httplib on Linux or macOS. Requires CMake 3.14 or later.

```bash
mkdir -p build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
sudo cmake --build . --target install
```

--------------------------------

### Control Methods

Source: https://github.com/yhirose/cpp-httplib/blob/master/README-sse.md

Starts the client in blocking or non-blocking mode, and stops it. start_async runs in a background thread.

```cpp
// Blocking start with auto-reconnect
sse.start();

// Non-blocking start (runs in background thread)
sse.start_async();

// Stop the client (thread-safe)
sse.stop();
```

--------------------------------

### Basic SSEClient usage with on_message and start

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/cookbook/e04-sse-client.md

Basic usage of the SSEClient class: create a Client, construct an SSEClient with a path, register an on_message callback, and call start() to begin the blocking event loop. The client automatically reconnects if the connection drops.

```cpp
#include <httplib.h>

httplib::Client cli("http://localhost:8080");
httplib::sse::SSEClient sse(cli, "/events");

sse.on_message([](const httplib::sse::SSEMessage &msg) {
  std::cout << "data: " << msg.data << std::endl;
});

sse.start(); // blocking
```

--------------------------------

### Access the server with client code

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/04-static-file-server.md

Uses the httplib::Client to GET the root URL and prints the response body.

```cpp
httplib::Client cli("http://localhost:8080");
auto res = cli.Get("/");
if (res) {
    std::cout << res->body << std::endl;  // HTML is displayed
}
```

--------------------------------

### Signal handlers and server listen

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/llm-app/ch04-model-management.md

Sets up SIGINT and SIGTERM handlers to allow graceful shutdown, prints the listening address, and starts the server on 127.0.0.1:8080.

```cpp
  // Allow the server to be stopped with `Ctrl+C` (`SIGINT`) or `kill` (`SIGTERM`)
  signal(SIGINT, signal_handler);
  signal(SIGTERM, signal_handler);

  std::cout << "Listening on http://127.0.0.1:8080" << std::endl;
  svr.listen("127.0.0.1", 8080);
```

--------------------------------

### Custom Headers Example

Source: https://github.com/yhirose/cpp-httplib/blob/master/README-sse.md

Passes custom headers (e.g., Authorization) to the constructor for authentication.

```cpp
httplib::Headers headers = {
    {"Authorization", "Bearer token123"}
};

httplib::sse::SSEClient sse(cli, "/events", headers);
sse.start();
```

--------------------------------

### SSEClient::start_async

Source: https://github.com/yhirose/cpp-httplib/blob/master/README-sse.md

Starts the SSE client in a non-blocking manner, running in a background thread.

```APIDOC
## SSEClient::start_async

### Description
Starts the SSE client in a non-blocking manner, running in a background thread.

### Method
Control

### Signature
```cpp
void start_async();
```

### Parameters
None

### Example
```cpp
sse.start_async();
```
```

--------------------------------

### Verify server with curl

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/01-getting-started.md

Sends a GET request to the running server and shows the expected response 'Hello, World!'.

```sh
curl http://localhost:8080/
# Hello, World!
```

--------------------------------

### Register routes for all HTTP verbs

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/03-basic-server.md

Shows the methods for each HTTP verb: Get, Post, Put, and Delete. Each registers a handler for the given path.

```cpp
svr.Get("/path",    handler);  // GET
svr.Post("/path",   handler);  // POST
svr.Put("/path",    handler);  // PUT
svr.Delete("/path", handler);  // DELETE
```

--------------------------------

### Equivalent curl command for GET request

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/02-basic-client.md

Shows the curl command that performs the same GET request as the C++ example. The output is shown as a comment.

```sh
curl http://localhost:8080/hi
# Hello!
```

--------------------------------

### Multiple path parameters with :org and :repo

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/cookbook/s03-path-params.md

Defines a GET route for `/orgs/:org/repos/:repo` and reads both parameters from `req.path_params`. Matches paths like `/orgs/anthropic/repos/cpp-httplib`.

```cpp
svr.Get("/orgs/:org/repos/:repo", [](const httplib::Request &req, httplib::Response &res) {
  auto org = req.path_params.at("org");
  auto repo = req.path_params.at("repo");
  res.set_content(org + "/" + repo, "text/plain");
});
```

--------------------------------

### Basic SSLServer setup with certificate and key files

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/cookbook/t03-ssl-server.md

Create an HTTPS server by passing PEM certificate and private key file paths to the httplib::SSLServer constructor. Register handlers and call listen() just like with httplib::Server.

```cpp
#define CPPHTTPLIB_OPENSSL_SUPPORT
#include <httplib.h>

int main() {
  httplib::SSLServer svr("cert.pem", "key.pem");

  svr.Get("/", [](const auto &req, auto &res) {
    res.set_content("hello over TLS", "text/plain");
  });

  svr.listen("0.0.0.0", 443);
}
```

--------------------------------

### Get query parameter with req.get_param_value()

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/03-basic-server.md

Use req.get_param_value() to retrieve a parameter by name, works for both GET query parameters and POST form data. The example registers a GET handler that reads the 'q' parameter and returns it.

```cpp
svr.Get("/search", [](const auto &req, auto &res) {
    auto q = req.get_param_value("q");
    res.set_content("Query: " + q, "text/plain");
});
```

--------------------------------

### main: server setup and endpoints

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/llm-app/ch05-web-ui.md

Sets up the server: creates model directory, auto-downloads default model if missing, initializes Llama, sets logger, and defines /health and /translate endpoints. The /translate endpoint validates JSON input and returns translation.

```cpp
int main() {
  // Create model storage directory
  auto models_dir = get_models_dir();
  std::filesystem::create_directories(models_dir);

  // Auto-download default model if not present
  std::string selected_model = MODELS[0].filename;
  auto path = models_dir / selected_model;
  if (!std::filesystem::exists(path)) {
    std::cout << "Downloading " << selected_model << "..." << std::endl;
    if (!download_model(MODELS[0], [](int pct) {
          std::cout << "\r" << pct << "%" << std::flush;
          return true;
        })) {
      std::cerr << "\nFailed to download model." << std::endl;
      return 1;
    }
    std::cout << std::endl;
  }
  auto llm = llamalib::Llama{path};

  svr.set_logger([](const auto &req, const auto &res) {
    std::cout << req.method << " " << req.path << " -> " << res.status
              << std::endl;
  });

  svr.Get("/health", [](const httplib::Request &, httplib::Response &res) {
    res.set_content(json{{"status", "ok"}}.dump(), "application/json");
  });

  // --- Translation endpoint (Chapter 2) ------------------------------------

  svr.Post("/translate",
           [&](const httplib::Request &req, httplib::Response &res) {
    auto input = json::parse(req.body, nullptr, false);
    if (input.is_discarded()) {
      res.status = 400;
      res.set_content(json{{"error", "Invalid JSON"}}.dump(),
                      "application/json");
      return;
    }

    if (!input.contains("text") || !input["text"].is_string() ||
        input["text"].get<std::string>().empty()) {
      res.status = 400;
      res.set_content(json{{"error", "'text' is required"}}.dump(),
                      "application/json");
      return;
    }

    auto text = input["text"].get<std::string>();
    auto target_lang = input.value("target_lang", "ja");

    auto prompt = "Translate the following text to " + target_lang +
                  ". Output only the translation, nothing else.\n\n" + text;

```

--------------------------------

### curl GET Request to https://nghttp2.org/

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/06-https-client.md

Equivalent curl command to fetch the homepage of https://nghttp2.org/. Used to compare with the C++ GET request example.

```sh
curl https://nghttp2.org/

```

--------------------------------

### Equivalent curl command with query parameters

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/02-basic-client.md

Shows the curl command that performs the same request as the C++ example with query parameters. The output is shown as a comment.

```sh
curl "http://localhost:8080/search?q=cpp-httplib"
# Query: cpp-httplib
```

--------------------------------

### Custom Event Types Example

Source: https://github.com/yhirose/cpp-httplib/blob/master/README-sse.md

Registers handlers for 'notification' and 'update' events, printing their data. Starts blocking.

```cpp
httplib::sse::SSEClient sse(cli, "/events");

sse.on_event("notification", [](const httplib::sse::SSEMessage &msg) {
    std::cout << "Notification: " << msg.data << std::endl;
});

sse.on_event("update", [](const httplib::sse::SSEMessage &msg) {
    std::cout << "Update: " << msg.data << std::endl;
});

sse.start();
```

--------------------------------

### SSE Protocol Format Example

Source: https://github.com/yhirose/cpp-httplib/blob/master/README-sse.md

Shows the SSE wire format: event, id, data fields, blank line separation, and comment lines.

```text
event: custom-type
id: 123
data: {"message": "hello"}

data: simple message

: this is a comment (ignored)
```

--------------------------------

### Set up a basic HTTP server with route handlers

Source: https://github.com/yhirose/cpp-httplib/blob/master/README.md

Creates a Server instance and registers GET handlers for '/hi', a regex path, a '/users/:id' path parameter, and '/body-header-param'. Demonstrates response content, path captures via req.matches, path params via req.path_params, and header/query parameter access. The final handler also retrieves all values for a repeated query key with req.get_param_values("tag").

```c++
#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");
    }
    // Get all values for a given key (e.g., ?tag=a&tag=b)
    auto values = req.get_param_values(
```

--------------------------------

### Error Handling Example

Source: https://github.com/yhirose/cpp-httplib/blob/master/README-sse.md

Sets an error handler that prints the error, configures reconnect interval and max attempts, then starts.

```cpp
sse.on_error([](httplib::Error err) {
    std::cerr << "Error: " << httplib::to_string(err) << std::endl;
});

sse.set_reconnect_interval(1000);
ssse.set_max_reconnect_attempts(5);

sse.start();
```

--------------------------------

### Main function: model setup and server endpoints

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/llm-app/ch04-model-management.md

Sets up the model directory, downloads the default model if missing, initializes the Llama instance, and defines HTTP endpoints for health, translation, and SSE streaming. Includes a mutex to protect model access during switching.

```cpp
int main() {
  // Create the model storage directory
  auto models_dir = get_models_dir();
  std::filesystem::create_directories(models_dir);

  // Automatically download the default model if not yet present
  std::string selected_model = MODELS[0].filename;
  auto path = models_dir / selected_model;
  if (!std::filesystem::exists(path)) {
    std::cout << "Downloading " << selected_model << "..." << std::endl;
    if (!download_model(MODELS[0], [](int pct) {
          std::cout << "\r" << pct << "%" << std::flush;
          return true;
        })) {
      std::cerr << "\nFailed to download model." << std::endl;
      return 1;
    }
    std::cout << std::endl;
  }
  auto llm = llamalib::Llama{path};
  std::mutex llm_mutex; // Protect access during model switching

  svr.set_logger([](const auto &req, const auto &res) {
    std::cout << req.method << " " << req.path << " -> " << res.status
              << std::endl;
  });

  svr.Get("/health", [](const httplib::Request &, httplib::Response &res) {
    res.set_content(json{{"status", "ok"}}.dump(), "application/json");
  });

  // --- Translation endpoint (Chapter 2) ------------------------------------

  svr.Post("/translate",
           [&](const httplib::Request &req, httplib::Response &res) {
    // JSON parsing and validation (see Chapter 2 for details)
    auto input = json::parse(req.body, nullptr, false);
    if (input.is_discarded()) {
      res.status = 400;
      res.set_content(json{{"error", "Invalid JSON"}}.dump(),
                      "application/json");
      return;
    }

    if (!input.contains("text") || !input["text"].is_string() ||
        input["text"].get<std::string>().empty()) {
      res.status = 400;
      res.set_content(json{{"error", "'text' is required"}}.dump(),
                      "application/json");
      return;
    }

    auto text = input["text"].get<std::string>();
    auto target_lang = input.value("target_lang", "ja");

    auto prompt = "Translate the following text to " + target_lang +
                  ". Output only the translation, nothing else.\n\n" + text;

    try {
      std::lock_guard<std::mutex> lock(llm_mutex);
      auto translation = llm.chat(prompt);
      res.set_content(json{{"translation", translation}}.dump(),
                      "application/json");
    } catch (const std::exception &e) {
      res.status = 500;
      res.set_content(json{{"error", e.what()}}.dump(), "application/json");
    }
  });

  // --- SSE streaming translation (Chapter 3) -------------------------------

  svr.Post("/translate/stream",
           [&](const httplib::Request &req, httplib::Response &res) {
    auto input = json::parse(req.body, nullptr, false);
    if (input.is_discarded()) {
      res.status = 400;
      res.set_content(json{{"error", "Invalid JSON"}}.dump(),
                      "application/json");
      return;
    }

    if (!input.contains("text") || !input["text"].is_string() ||
        input["text"].get<std::string>().empty()) {
      res.status = 400;
      res.set_content(json{{"error", "'text' is required"}}.dump(),
                      "application/json");
      return;
    }

    auto text = input["text"].get<std::string>();
    auto target_lang = input.value("target_lang", "ja");

    auto prompt = "Translate the following text to " + target_lang +
                  ". Output only the translation, nothing else.\n\n" + text;

    res.set_chunked_content_provider(
        "text/event-stream",
        [&, prompt](size_t, httplib::DataSink &sink) {
          std::lock_guard<std::mutex> lock(llm_mutex);
          try {
            llm.chat(prompt, [&](std::string_view token) {
              sink.os << "data: "
                      << json(std::string(token)).dump(
                           -1, ' ', false, json::error_handler_t::replace)
                      << "\n\n";
              return sink.os.good(); // Abort inference on disconnect
            });
            sink.os << "data: [DONE]\n\n";
          } catch (const std::exception &e) {
            sink.os << "data: " << json({{"error", e.what()}}).dump() << "\n\n";
          }
          sink.done();
          return true;
        });
  });

  // --- Model list (Chapter 4) ----------------------------------------------
}
```

--------------------------------

### Initialize model with download and mutex in main()

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/llm-app/ch04-model-management.md

Sets up the models directory, selects the first model from MODELS, downloads it if not present, creates the Llama instance, and adds a std::mutex to protect concurrent access during model switching.

```cpp
int main() {
  auto models_dir = get_models_dir();
  std::filesystem::create_directories(models_dir);

  std::string selected_model = MODELS[0].filename;
  auto path = models_dir / selected_model;

  // Automatically download the default model if not yet present
  if (!std::filesystem::exists(path)) {
    std::cout << "Downloading " << selected_model << "..." << std::endl;
    if (!download_model(MODELS[0], [](int pct) {
          std::cout << "\r" << pct << "%" << std::flush;
          return true;
        })) {
      std::cerr << "\nFailed to download model." << std::endl;
      return 1;
    }
    std::cout << std::endl;
  }
  auto llm = llamalib::Llama{path};
  std::mutex llm_mutex; // Protect access during model switching
  // ...
}
```

--------------------------------

### GET request with regex route

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/02-basic-client.md

The test server has a /files/(\d+) route that accepts numeric IDs only. This example shows a successful request with a numeric ID.

```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
```

--------------------------------

### Read request header with req.get_header_value()

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/03-basic-server.md

Use req.get_header_value() to read a request header by name. The example registers a GET handler that reads the Authorization header and returns it in the response.

```cpp
svr.Get("/check", [](const auto &req, auto &res) {
    auto auth = req.get_header_value("Authorization");
    res.set_content("Auth: " + auth, "text/plain");
});
```

--------------------------------

### Create project directory and initialize git repository

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/llm-app/ch01-setup.md

Commands to create the project directory, subdirectories (src and models), and initialize a git repository. Run these in a terminal.

```bash
mkdir translate-app && cd translate-app
mkdir src models
git init
```

--------------------------------

### Large File Download with Progress

Source: https://github.com/yhirose/cpp-httplib/blob/master/README-stream.md

Downloads a file from example.com and writes it to download.zip, printing progress in KB. Fails with an error message if the request fails or the status is not 200.

```cpp
#include "httplib.h"
#include <fstream>
#include <iostream>

int main() {
    httplib::Client cli("http://example.com");
    auto result = httplib::stream::Get(cli, "/large-file.zip");
    
    if (!result || result.status() != 200) {
        std::cerr << "Download failed\n";
        return 1;
    }
    
    std::ofstream file("download.zip", std::ios::binary);
    size_t total = 0;
    
    while (result.next()) {
        file.write(result.data(), result.size());
        total += result.size();
        std::cout << "\rDownloaded: " << (total / 1024) << " KB" << std::flush;
    }
    
    std::cout << "\nComplete!\n";
    return 0;
}

```

--------------------------------

### Get uploaded file with req.form.get_file()

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/03-basic-server.md

Use req.form.get_file() to access files uploaded via multipart form data. The example registers a POST handler that retrieves the file named 'file' and returns its filename and size.

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

--------------------------------

### SSE event format example

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/llm-app/ch03-sse-streaming.md

Shows the plain-text format of SSE events: each line starts with 'data:' and events are separated by blank lines. Tokens are sent as escaped JSON strings, so they appear in double quotes.

```text
data: "去年の"
data: "春に"
data: "東京を"
data: [DONE]
```

--------------------------------

### Run server on background thread with WebView

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/llm-app/ch06-desktop-app.md

Starts the server on a background thread using bind_to_any_port and listen_after_bind, then runs the WebView UI on the main thread. Shutdown order is important: stop the server and join the thread after the window closes.

```cpp
#include "webview/webview.h"
#include <thread>

int main() {
  // ... (server setup is the same as Chapter 5) ...

  // Start the server on a background thread
  auto port = svr.bind_to_any_port("127.0.0.1");
  std::thread server_thread([&]() { svr.listen_after_bind(); });

  std::cout << "Listening on http://127.0.0.1:" << port << std::endl;

  // Display the UI with WebView
  webview::webview w(false, nullptr);
  w.set_title("Translate App");
  w.set_size(1024, 768, WEBVIEW_HINT_NONE);
  w.navigate("http://127.0.0.1:" + std::to_string(port));
  w.run(); // Block until the window is closed

  // Stop the server when the window is closed
  svr.stop();
  server_thread.join();
}
```

--------------------------------

### Switch to a different model

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/llm-app/ch04-model-management.md

POST to /models/select to switch to gemma-2-9b-it. Download progress streams via SSE, and "ready" appears when done.

```bash
curl -N -X POST http://localhost:8080/models/select \
  -H "Content-Type: application/json" \
  -d '{"model": "gemma-2-9b-it"}'
```

--------------------------------

### Main server setup and endpoints

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/llm-app/ch06-desktop-app.md

Sets up the HTTP server, auto-downloads the default model if missing, and defines /health and /translate endpoints. The /translate endpoint validates JSON input and requires a non-empty 'text' field, defaulting target_lang to 'ja'.

```cpp
int main() {
  httplib::Server svr;
  // Create the model storage directory
  auto models_dir = get_models_dir();
  std::filesystem::create_directories(models_dir);

  // Auto-download the default model if not already present
  std::string selected_model = MODELS[0].filename;
  auto path = models_dir / selected_model;
  if (!std::filesystem::exists(path)) {
    std::cout << "Downloading " << selected_model << "..." << std::endl;
    if (!download_model(MODELS[0], [](int pct) {
          std::cout << "\r" << pct << "%" << std::flush;
          return true;
        })) {
      std::cerr << "\nFailed to download model." << std::endl;
      return 1;
    }
    std::cout << std::endl;
  }
  auto llm = llamalib::Llama{path};
  std::mutex llm_mutex; // Protect access during model switching

  svr.set_logger([](const auto &req, const auto &res) {
    std::cout << req.method << " " << req.path << " -> " << res.status
              << std::endl;
  });

  svr.Get("/health", [](const httplib::Request &, httplib::Response &res) {
    res.set_content(json{{"status", "ok"}}.dump(), "application/json");
  });

  // --- Translation endpoint (Chapter 2) ------------------------------------

  svr.Post("/translate",
           [&](const httplib::Request &req, httplib::Response &res) {
    auto input = json::parse(req.body, nullptr, false);
    if (input.is_discarded()) {
      res.status = 400;
      res.set_content(json{{"error", "Invalid JSON"}}.dump(),
                      "application/json");
      return;
    }

    if (!input.contains("text") || !input["text"].is_string() ||
        input["text"].get<std::string>().empty()) {
      res.status = 400;
      res.set_content(json{{"error", "'text' is required"}}.dump(),
                      "application/json");
      return;
    }

    auto text = input["text"].get<std::string>();
    auto target_lang = input.value("target_lang", "ja");

    auto prompt = "Translate the following text to " + target_lang +
                  ". Output only the translation, nothing else.\n\n" + text;

  });
}
```

--------------------------------

### Basic usage of bind_to_any_port() with listen_after_bind()

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/cookbook/s17-bind-any-port.md

Binds the server to any available port on 0.0.0.0, prints the assigned port, then starts listening. bind_to_any_port() is equivalent to passing 0 as the port; the OS assigns a free one. You must call listen_after_bind() separately because bind and listen cannot be combined in one call.

```cpp
httplib::Server svr;

svr.Get("/", [](const auto &req, auto &res) {
  res.set_content("hello", "text/plain");
});

int port = svr.bind_to_any_port("0.0.0.0");
std::cout << "listening on port " << port << std::endl;

svr.listen_after_bind();
```

--------------------------------

### Create html directory and index.html

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/04-static-file-server.md

Commands to create the html directory and the index.html file that will be served by the basic server.

```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>
```

--------------------------------

### Streaming GET with content_receiver callback

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/09-whats-next.md

Pass a content_receiver callback to Get() for streaming responses. This approach works with Keep-Alive connections.

```cpp
httplib::Client cli("http://localhost:8080");

cli.Get("/stream", [](const char *data, size_t len) {
    std::cout.write(data, len);
    return true;
});
```

--------------------------------

### Main function with embedded file serving and WebView

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/llm-app/ch06-desktop-app.md

Replaces set_mount_point with httplib::mount, uses bind_to_any_port and listen_after_bind, and runs a WebView window. Includes macOS edit menu setup and server shutdown on window close.

```cpp
  // --- Embedded file serving (Chapter 6) ------------------------------------
  // Chapter 5: svr.set_mount_point("/", "./public");
  httplib::mount(svr, Web::FS);

  // Start the server on a background thread
  auto port = svr.bind_to_any_port("127.0.0.1");
  std::thread server_thread([&]() { svr.listen_after_bind(); });

  std::cout << "Listening on http://127.0.0.1:" << port << std::endl;

  // Display the UI with WebView
  webview::webview w(false, nullptr);
  w.set_title("Translate App");
  w.set_size(1024, 768, WEBVIEW_HINT_NONE);
  w.navigate("http://127.0.0.1:" + std::to_string(port));

#ifdef __APPLE__
  setup_macos_edit_menu();
#endif
  w.run(); // Block until the window is closed

  // Stop the server when the window is closed
  svr.stop();
  server_thread.join();
}
```

--------------------------------

### GET request with custom headers

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/02-basic-client.md

Pass an httplib::Headers object to add custom HTTP headers. 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
```

--------------------------------

### Build commands for the desktop app

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/llm-app/ch06-desktop-app.md

Configure and build the project with CMake.

```bash
cmake -B build
cmake --build build -j
```

--------------------------------

### GET request with path parameter

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/02-basic-client.md

Pass the path directly to Get() to embed values in the URL. The response body is printed if the request succeeds.

```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
```

--------------------------------

### Get (route handler)

Source: https://github.com/yhirose/cpp-httplib/blob/master/README.md

Registers a GET route handler. The handler is called after pre-routing and pre-request handlers, and the request body is read before the handler runs.

```APIDOC
## GET /me

### Description
Registers a GET route handler for the path `/me`. The handler can access data stored in `res.user_data` by pre-routing handlers.

### Method
GET

### Endpoint
/me

### Parameters
#### Path Parameters
- **none** - No path parameters.

#### Query Parameters
- **none** - No query parameters.

#### Request Body
- **none** - No request body.

### Request Example
```cpp
svr.Get("/me", [](const Request& /*req*/, Response& res) {
  auto* ctx = res.user_data.get<AuthContext>("auth");
  if (!ctx) {
    res.status = StatusCode::Unauthorized_401;
    return;
  }
  res.set_content("Hello " + ctx->user_id, "text/plain");
});
```

### Response
#### Success Response (200)
- **content** (string) - The response body, e.g., "Hello <user_id>" with content type "text/plain".

#### Error Response (401)
- **status** (int) - Status code 401 Unauthorized when no auth context is found.

### Response Example
```cpp
// Success
res.set_content("Hello user123", "text/plain");
// Error
res.status = StatusCode::Unauthorized_401;
```
```

--------------------------------

### Initial index.html

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/llm-app/ch05-web-ui.md

A minimal HTML page that displays 'Hello!' to verify static file serving.

```html
<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8">
  <title>Translate App</title>
</head>
<body>
  <h1>Hello!</h1>
</body>
</html>
```

--------------------------------

### GET /hi

Source: https://github.com/yhirose/cpp-httplib/blob/master/README.md

Registers a GET handler for the /hi path that returns a plain text response. This demonstrates the basic server route registration pattern.

```APIDOC
## GET /hi

### Description
Registers a GET handler for the /hi path that returns a plain text response.

### Method
GET

### Endpoint
/hi

### Parameters
None

### Response
#### Success Response (200)
- **Content-Type**: text/plain
- **Body**: "Hello World!"

### Response Example
Hello World!
```

--------------------------------

### Register GET route with svr.Get()

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/03-basic-server.md

Registers a handler for GET requests to /hi. The lambda receives the request and response objects and sets the response content to 'Hello!' with text/plain content type.

```cpp
httplib::Server svr;

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

--------------------------------

### Basic static file serving with set_mount_point

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/cookbook/s04-static-files.md

Maps the root URL path to the local './public' directory and starts the server on port 8080. Files like './public/index.html' become accessible at 'http://localhost:8080/index.html'.

```cpp
httplib::Server svr;
svr.set_mount_point("/", "./public");
svr.listen("0.0.0.0", 8080);
```

--------------------------------

### GET request with query parameters using httplib::Params

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/tour/02-basic-client.md

Adds a query parameter 'q' with value 'cpp-httplib' to a GET request. httplib::Params automatically URL-encodes special characters.

```cpp
auto res = cli.Get("/search", httplib::Params{{"q", "cpp-httplib"}});
if (res) {
    std::cout << res->body << std::endl;  // Query: cpp-httplib
}
```

--------------------------------

### Enable compression support with CPPHTTPLIB_*_SUPPORT macros

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/cookbook/c15-compression.md

Define these macros before including httplib.h to enable compression support. Link against zlib, brotli, or zstd depending on which macros you define.

```cpp
#define CPPHTTPLIB_ZLIB_SUPPORT    // gzip / deflate
#define CPPHTTPLIB_BROTLI_SUPPORT  // brotli
#define CPPHTTPLIB_ZSTD_SUPPORT    // zstd
#include <httplib.h>
```

--------------------------------

### Test pattern using bind_to_any_port() with a client

Source: https://github.com/yhirose/cpp-httplib/blob/master/docs-src/pages/en/cookbook/s17-bind-any-port.md

Starts a server on a random port on 127.0.0.1, runs it on a separate thread, and uses a client to hit the /ping endpoint. The port is assigned at runtime, so parallel test runs don't collide. bind_to_any_port() returns -1 on failure (permission errors, no available ports, etc.), so always check the return value.

```cpp
httplib::Server svr;
svr.Get("/ping", [](const auto &, auto &res) { res.set_content("pong", "text/plain"); });

int port = svr.bind_to_any_port("127.0.0.1");
std::thread t([&] { svr.listen_after_bind(); });

// run the test while the server is up on another thread
httplib::Client cli("127.0.0.1", port);
auto res = cli.Get("/ping");
assert(res && res->body == "pong");

svr.stop();
t.join();
```
Tokens:
Raw