cpp-httplib/docs-src/pages/en/cookbook/index.md

---

title: "Cookbook" order: 0

status: "draft"

A collection of recipes that answer "How do I...?" questions. Each recipe is self-contained — read only what you need. For an introduction to the basics, see the Tour.

Client

Basics

• C01. Get the response body / save to a file
• C02. Send and receive JSON
• C03. Set default headers
• C04. Follow redirects

Authentication

• C05. Use Basic authentication
• C06. Call an API with a Bearer token

File Upload

• C07. Upload a file as multipart form data
• C08. POST a file as raw binary
• C09. Send the body with chunked transfer

Streaming & Progress

• C10. Receive a response as a stream
• C11. Use the progress callback

Connection & Performance

• C12. Set timeouts
• C13. Set an overall timeout
• C14. Understand connection reuse and Keep-Alive behavior
• C15. Enable compression
• C16. Send requests through a proxy

Error Handling & Debugging

• C17. Handle error codes
• C18. Handle SSL errors
• C19. Set up client logging

Server

Basics

• S01. Register GET / POST / PUT / DELETE handlers
• S02. Receive JSON requests and return JSON responses
• S03. Use path parameters (/users/:id)
• S04. Set up a static file server (set_mount_point)

Streaming & Files

• S05. Stream a large file in the response (ContentProvider)
• S06. Return a file download response (Content-Disposition)
• S07. Receive multipart data as a stream (ContentReader)
• S08. Compress responses (gzip)

Handler Chain

• S09. Add pre-processing to all routes (Pre-routing handler)
• S10. Add response headers with a Post-routing handler (CORS, etc.)
• S11. Authenticate per route with a Pre-request handler (matched_route)
• S12. Pass data between handlers with res.user_data

Error Handling & Debugging

• S13. Return custom error pages (set_error_handler)
• S14. Catch exceptions (set_exception_handler)
• S15. Log requests (Logger)
• S16. Detect client disconnection (req.is_connection_closed())

Operations & Tuning

• S17. Assign a port dynamically (bind_to_any_port)
• S18. Control startup order with listen_after_bind
• S19. Shut down gracefully (stop() and signal handling)
• S20. Tune Keep-Alive (set_keep_alive_max_count / set_keep_alive_timeout)
• S21. Configure the thread pool (new_task_queue)
• S22. Communicate over Unix domain sockets (set_address_family(AF_UNIX))

TLS / Security

• T01. Choosing between OpenSSL, mbedTLS, and wolfSSL (build-time #define differences)
• T02. Control SSL certificate verification (disable, custom CA, custom callback)
• T03. Set up an SSL/TLS server (certificate and private key)
• T04. Configure mTLS (mutual TLS with client certificates)
• T05. Access the peer certificate on the server (req.peer_cert() / SNI)

SSE

• E01. Implement an SSE server
• E02. Use event names to distinguish event types
• E03. Handle reconnection (Last-Event-ID)
• E04. Receive SSE events on the client

WebSocket

• W01. Implement a WebSocket echo server and client
• W02. Configure heartbeats (set_websocket_ping_interval)
• W03. Handle connection close
• W04. Send and receive binary frames