pulsatrix 1.1.0
Loading...
Searching...
No Matches
http.hpp
Go to the documentation of this file.
1
5#pragma once
6
7#include <chrono>
8#include <cstddef>
9#include <cstdint>
10#include <functional>
11#include <memory>
12#include <stdexcept>
13#include <string>
14#include <string_view>
15#include <utility>
16#include <vector>
17
19
20namespace pulsatrix::orch {
21
23struct HttpHeader {
24 std::string name;
25 std::string value;
26 bool sensitive = false;
27};
28
31 std::string method = "POST";
33 std::string url;
34 std::vector<HttpHeader> headers;
35 std::string body;
37 std::chrono::milliseconds connect_timeout{10'000};
40 std::chrono::milliseconds read_timeout{600'000};
42 std::size_t max_response_bytes = std::size_t{64} << 20;
43
45 void add_header(std::string name, std::string value);
47 void add_secret_header(std::string name, const Secret& secret);
48
50 [[nodiscard]] std::string describe() const;
51};
52
55 int status = 0;
57 std::vector<std::pair<std::string, std::string>> headers;
59 std::string body;
60
62 [[nodiscard]] const std::string* header(std::string_view name) const;
63 [[nodiscard]] bool ok() const { return status >= 200 && status < 300; }
64};
65
67class HttpError : public std::runtime_error {
68public:
69 enum class Kind {
71 Connect,
72 Tls,
73 Timeout,
74 TooLarge,
75 Protocol,
76 Other,
77 };
78 HttpError(Kind kind, const std::string& message) : std::runtime_error(message), kind_(kind) {}
79 [[nodiscard]] Kind kind() const { return kind_; }
80
81private:
82 Kind kind_;
83};
84
86using HttpChunkHandler = std::function<bool(std::string_view chunk)>;
87
90public:
91 virtual ~HttpTransport() = default;
92
97 [[nodiscard]] virtual HttpResponse send(const HttpRequest& request) = 0;
98
107 [[nodiscard]] virtual HttpResponse stream(const HttpRequest& request, const HttpChunkHandler& on_chunk) = 0;
108
110 [[nodiscard]] virtual std::string name() const = 0;
111};
112
114enum class HttpBackend {
115 Httplib,
116 Curl,
117};
118
123 std::string ca_cert_file;
124};
125
127[[nodiscard]] bool HttpBackendAvailable(HttpBackend backend);
129[[nodiscard]] bool HttpsSupported(HttpBackend backend);
130
135[[nodiscard]] std::unique_ptr<HttpTransport> MakeHttpTransport(HttpBackend backend, HttpTransportOptions options = {});
136
139[[nodiscard]] std::unique_ptr<HttpTransport> MakeHttpTransport(HttpTransportOptions options = {});
140
142struct HttpUrl {
143 bool https = false;
144 std::string host;
145 uint16_t port = 0;
146 std::string target;
147};
148
154[[nodiscard]] HttpUrl ParseHttpUrl(std::string_view url);
155
156} // namespace pulsatrix::orch
A request that got no complete response: the connection, TLS, a timeout or a limit failed.
Definition http.hpp:67
Kind kind() const
Definition http.hpp:79
Kind
Definition http.hpp:69
@ TooLarge
the body passed max_response_bytes
@ Protocol
the response wasn't valid HTTP, or the connection closed mid-response
@ Timeout
connect_timeout or read_timeout passed
@ InvalidRequest
a malformed URL or header, before anything is sent
@ Tls
the handshake or certificate verification failed, or the build has no TLS
HttpError(Kind kind, const std::string &message)
Definition http.hpp:78
Sends HTTP requests. One instance may be used by one thread at a time.
Definition http.hpp:89
virtual std::string name() const =0
The backend and its TLS library, for example cpp-httplib 0.57.1 (OpenSSL 3.5.5).
virtual HttpResponse stream(const HttpRequest &request, const HttpChunkHandler &on_chunk)=0
Sends request and passes a successful (2xx) response's body to on_chunk as it arrives,...
virtual ~HttpTransport()=default
virtual HttpResponse send(const HttpRequest &request)=0
Sends request and waits for the whole response.
Holds a credential, such as an LLM provider's API key.
Definition secret.hpp:20
Definition http.hpp:20
std::function< bool(std::string_view chunk)> HttpChunkHandler
Receives a streamed body chunk by chunk. Return false to cancel the request.
Definition http.hpp:86
bool HttpsSupported(HttpBackend backend)
Whether backend can make HTTPS requests in this build.
HttpUrl ParseHttpUrl(std::string_view url)
Parses an http:// or https:// URL.
bool HttpBackendAvailable(HttpBackend backend)
Whether this build has backend.
HttpBackend
The HTTP libraries a transport can use.
Definition http.hpp:114
@ Curl
libcurl, with PULSATRIX_ORCHESTRATOR_CURL; its own TLS (Schannel on Windows)
@ Httplib
cpp-httplib, always built; HTTPS when the build found OpenSSL
std::unique_ptr< HttpTransport > MakeHttpTransport(HttpBackend backend, HttpTransportOptions options={})
A transport using backend.
A credential such as an API key, which can't be printed by accident.
One request header. A sensitive one (a credential) is redacted by HttpRequest::describe().
Definition http.hpp:23
std::string name
Definition http.hpp:24
std::string value
Definition http.hpp:25
bool sensitive
Definition http.hpp:26
An HTTP request. Redirects are never followed, so a credential only goes to url.
Definition http.hpp:30
std::vector< HttpHeader > headers
Definition http.hpp:34
std::string describe() const
The method, URL and headers, with sensitive values redacted, for logs and errors.
std::string method
Definition http.hpp:31
void add_header(std::string name, std::string value)
Adds a header.
std::string url
An http:// or https:// URL.
Definition http.hpp:33
std::chrono::milliseconds connect_timeout
The longest the connection (and TLS handshake) may take.
Definition http.hpp:37
std::size_t max_response_bytes
The most response body bytes to accept, against a server that never stops.
Definition http.hpp:42
std::string body
Definition http.hpp:35
std::chrono::milliseconds read_timeout
The longest the server may go without sending a byte. A streamed response can last longer than this i...
Definition http.hpp:40
void add_secret_header(std::string name, const Secret &secret)
Adds a header whose value is secret, marked sensitive.
An HTTP response. A status of 400 or 500 is a response, not an error.
Definition http.hpp:54
int status
Definition http.hpp:55
std::vector< std::pair< std::string, std::string > > headers
Response headers in the order received, names in lowercase.
Definition http.hpp:57
const std::string * header(std::string_view name) const
The first header named name (any case), or nullptr if there is none.
std::string body
The body. Empty when HttpTransport::stream() delivered it to its callback.
Definition http.hpp:59
bool ok() const
Definition http.hpp:63
How a transport trusts servers. Certificate verification can't be turned off.
Definition http.hpp:120
std::string ca_cert_file
A PEM file of the CA certificates to trust instead of the system's, for example a company proxy's or ...
Definition http.hpp:123
An http or https URL split into its parts.
Definition http.hpp:142
uint16_t port
the scheme's default when the URL has none
Definition http.hpp:145
bool https
Definition http.hpp:143
std::string host
without brackets for an IPv6 literal
Definition http.hpp:144
std::string target
the path and query, at least /
Definition http.hpp:146