Orbit Framework 2.0.0
A high-performance asynchronous C++20 HTTP server framework.
Loading...
Searching...
No Matches
HTTP Client

orbit::http::Client makes outbound HTTP requests (to other services, OAuth2 providers, webhooks) without blocking the server's worker threads. One background thread drives every transfer through libcurl's multi interface, so many requests run concurrently and connections to the same host are kept alive and reused.

Coroutines

orbit::concurrency::Task notify(std::shared_ptr<orbit::http::ResponseWriter> writer) {
req.method = "POST";
req.url = "https://hooks.example.com/orders";
req.headers = {{"Content-Type", "application/json"}};
req.body = R"({"order": 42})";
if (!res.ok()) {
out.status(orbit::http::HttpStatus::BadGateway).send("upstream failed: " + res.error);
} else {
out.send("upstream said " + std::to_string(res.status));
}
writer->send(std::move(out));
}
static Client & shared()
A process-wide client, created on first use.
ClientSendAwaiter send_async(ClientRequest request)
Awaitable form of send(); the coroutine resumes on the client's thread.
Definition Client.hpp:94
Represents an HTTP response to be sent to a client.
Definition HttpResponse.hpp:107
HttpResponse & status(HttpStatus code) &
Sets the HTTP status code of the response.
Definition HttpResponse.hpp:167
HttpResponse & send(const std::string &b) &
Sets the response body as plain text.
Definition HttpResponse.hpp:174
Fire-and-forget coroutine type, used as the return type of coroutine route handlers.
Definition Task.hpp:36
An outbound HTTP request for Client.
Definition Client.hpp:16
std::string url
http:// or https:// only
Definition Client.hpp:18
std::string method
Definition Client.hpp:17
std::string body
Definition Client.hpp:20
std::vector< std::pair< std::string, std::string > > headers
Definition Client.hpp:19
The result of a ClientRequest.
Definition Client.hpp:32
std::string error
Empty on success.
Definition Client.hpp:37
bool ok() const
True if a response arrived (any status, including 4xx and 5xx).
Definition Client.hpp:40
long status
0 if no response arrived
Definition Client.hpp:33

Callbacks and blocking calls

// runs on the client's thread
});
// From code that has to block (not from inside a callback):
void send(ClientRequest request, std::function< void(ClientResponse)> on_done)
Starts request; on_done is called once, on the client's thread.
ClientResponse send_sync(ClientRequest request)
Sends request and waits for the response, blocking the calling thread (for code that cannot be asynch...

res.ok() means a response arrived; check res.status for the HTTP status (a 404 is a successful request). Failures (DNS, connection refused, TLS, timeout, size limit) set res.error and leave status at 0. res.header("Content-Type") looks a header up case-insensitively; res.effective_url is the URL after redirects.

Options per request

Field Default
timeout 30 s Whole request, redirects included
connect_timeout 10 s
follow_redirects / max_redirects on / 5 Only to http/https URLs
verify_tls on Certificate chain and host name
ca_file system store PEM bundle, e.g. for a private CA
max_response_size 10 MB Larger responses fail instead of filling memory

Only http:// and https:// URLs are fetched, including on redirects, so a redirect cannot make the server read file:// or other schemes. Compressed responses are decoded automatically.

Threads

Callbacks, and coroutines resumed by send_async(), run on the client's thread. Keep that work short: answer the request, or hand anything slow to the thread pool. send_sync() called on that thread fails immediately rather than waiting forever.

orbit::http::Client::shared() is a process-wide instance; create your own orbit::http::Client for a separate connection pool or user agent (ClientOptions::user_agent). Destroying a client completes its pending requests with the error client shut down.

The OAuth2 middleware and JWKS key fetching (jwt_auth) use the shared client.