Cookbook

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
• S04. Set up a static file server

Streaming & Files

• S05. Stream a large file in the response
• S06. Return a file download response
• S07. Receive multipart data as a stream
• S08. Return a compressed response

Handler Chain

• S09. Add pre-processing to all routes
• S10. Add response headers with a post-routing handler
• S11. Authenticate per route with a pre-request handler
• S12. Pass data between handlers with res.user_data

Error Handling & Debugging

• S13. Return custom error pages
• S14. Catch exceptions
• S15. Log requests
• S16. Detect client disconnection

Operations & Tuning

• S17. Bind to any available port
• S18. Control startup order with listen_after_bind
• S19. Shut down gracefully
• S20. Tune Keep-Alive
• S21. Configure the thread pool
• S22. Talk over a Unix domain socket

TLS / Security

• T01. Choosing between OpenSSL, mbedTLS, and wolfSSL
• T02. Control SSL certificate verification
• T03. Start an SSL/TLS server
• T04. Configure mTLS
• T05. Access the peer certificate on the server

SSE

• E01. Implement an SSE server
• E02. Use named events in SSE
• E03. Handle SSE reconnection
• E04. Receive SSE on the client

WebSocket

• W01. Implement a WebSocket echo server and client
• W02. Set a WebSocket heartbeat
• W03. Handle connection close
• W04. Send and receive binary frames
• W05. Configure TLS for wss:// connections
• W06. Set timeouts